Bir uç nokta tanımladınız ve uygulamanızdan çağırmak istiyorsunuz. Zorlayıcı kısım, spesifikasyonu çalışan koda çevirmektir: doğru URL, başlıklar, kimlik doğrulama belirteci, sorgu dizesi, hepsi bir requests çağrısına veya bir fetch işlemine bağlanmış. Tek bir karakteri yanlış kopyalarsanız, sunucunun neden 401 döndürdüğünü merak ederek yirmi dakika harcarsınız.
Bu kalıp kodu elle yazmak zorunda değilsiniz. API'nız Apidog'da tasarlandıysa, platform uç nokta spesifikasyonunuzu okur ve çalıştığınız dilde, yapıştırmaya hazır bir istek kodu parçacığı sunar: hızlı bir terminal kontrolü için cURL, bir betik için Python requests, bir ön uç için JavaScript fetch veya Axios. Bu kılavuz, gerçek bir uç noktadan bu kodu nasıl oluşturacağınızı, gerçek değerleri taşıyan kodu elde etmek için isteği ne zaman önce göndermeniz gerektiğini ve spesifikasyonunuz değiştikçe oluşturulan kodu nasıl doğru tutacağınızı açıklar. Daha geniş seçenek yelpazesini isterseniz, API kod oluşturma araçları derlememiz size daha geniş bir bakış açısı sunar; burada yerleşik jeneratörle uygulamalı olarak çalışıyoruz.
Bu fikir, spesifikasyonun tek doğruluk kaynağı olması prensibine dayanır; bu, OpenAPI Spesifikasyonu'nun arkasındaki aynı prensiptir. Tanımı bir kez doğru yapın, istek kodu da onu takip edecektir.
İstemci kod oluşturucu aslında ne yapar
Apidog, bir uç nokta tanımını, dil varyantına göre bir istek kod parçacığına dönüştürür. GET /orders adresini işaretleyin, Python'ı ve Requests kütüphanesini seçin, ve spesifikasyonunuzun belirttiği başlıklar ve parametrelerle o yola isabet eden çağrıyı yazar. Bu bir istek oluşturucudur: seçtiğiniz dil ve HTTP kütüphanesinin sözdiziminde tek bir çağrı için kod üretir.
Bir noktada beklentileri doğru ayarlayın. Bu özellik, bir uç nokta için istek veya istemci kodu üretir, tam bir SDK veya sürümlü bir istemci kütüphane paketi değil. Kodunuza bırakabileceğiniz bir cURL satırı, bir Python requests bloğu veya bir JS fetch kodu parçacığına ihtiyacınız varsa, tam olarak bunu elde edersiniz. Belgeler tam bir kütüphane oluşturucuyu açıklamadığından, modeller ve sayfalama yardımcıları ile birlikte gelen, indirilebilir, tür atanmış bir SDK beklemeyin.
Bu, önce tasarım API geliştirme iş akışıyla doğal olarak eşleşir. Sözleşmeyi tanımlarsınız, doğrudan ondan istek kodunu oluşturursunuz ve her tüketici, Slack'e yapıştırılmış bir ekran görüntüsü yerine aynı doğru tanımdan başlar.
Oluşturucuyu açmanın iki yolu
Apidog, aynı özelliğe iki giriş noktası sunar. Hali hazırda bulunduğunuz yere uyanı kullanın.
İlki belgelerden. API'nız için Belgeler sekmesini açın, ardından sağ taraftaki İstemci Kodu Oluştur düğmesine tıklayın. Bu, bir uç noktanın belgelerini okurken ve onun için çağrıyı istediğinizde en hızlı yoldur.
İkincisi çalıştırıcıdan. API'nin Çalıştır sekmesinde, kod simgesine </> tıklayın. Bu, istekleri oluşturup gönderdiğiniz yerin yanında bulunur, bu nedenle çağrıyı zaten test ederken doğal bir seçimdir.
Her ikisi de aynı paneli açar. Buradan bir dil ve bir varyant seçersiniz ve Apidog kod parçacığını yazar.
GET /orders için bir Python istemci çağrısı oluşturun
İşte gerçekçi bir uç nokta ile tam akış: bir müşterinin siparişlerini listeleyen, duruma göre filtrelenen ve sayfalandırılan bir GET /orders çağrısı.
Adım 1: Uç noktayı açın ve dilinizi seçin
Uç nokta için Belgeler sekmesini açın ve İstemci Kodu Oluştur'a tıklayın. Panelde hedefinizi seçin. Apidog, uzun bir dil ve varyant listesini destekler, böylece yığınınıza tam olarak uyabilirsiniz:
- Shell: cURL, cURL-Windows, Httpie, wget, PowerShell
- JavaScript: Fetch, Axios, jQuery, XHR, Native, Request, Unirest
- Python: http.client, Requests
- Java: Unirest, OkHttp
- Go: Native
- PHP: cURL, Guzzle, pecl_http, HTTP_Request2
- Diğerleri: Swift (URLSession), C (libcurl), C#, Objective-C, Ruby, OCaml, Dart, R, ayrıca ham bir HTTP seçeneği
Bu örnek için Python ve Requests varyantını seçin. Apidog, spesifikasyondan buna benzer bir şey üretir:
import requests
url = "https://api.example.com/orders"
querystring = {"status": "shipped", "page": "1"}
headers = {"Accept": "application/json"}
response = requests.get(url, headers=headers, params=querystring)
print(response.json())
Kopyalayın, betiğinize bırakın ve çalışan bir çağrı elde edin. İşte önce tasarım yaklaşımı budur: kod parçacığı, uç noktanızın tam olarak neyi bildirdiğini yansıtır.
Adım 2: Yalnızca spesifikasyona dayalı kod parçacığının neleri içerdiğini bilin
Yapıştırmadan önce anlaşılması gereken bir nüans var. Doğrudan API spesifikasyonundan oluşturulan kod, yalnızca API spesifikasyonunu içerir, gerçek istek parametre değerlerini veya kimlik doğrulama belirtecinizi değil. Çağrının şeklini ve spesifikasyonda tanımlanan herhangi bir örnek değeri alırsınız, ancak korumalı bir uç noktaya gerçekten ulaşmak için ihtiyacınız olan canlı Authorization: Bearer ... başlığını almazsınız.
Kimlik doğrulaması olmayan bir çağrı veya belirteci kendiniz dolduracağınız zaman bu sorun değil. Korumalı bir GET /orders için, kodda gerçek değerleri istersiniz.
Adım 3: Gerçek değerleri yakalamak için önce isteği gönderin
Gerçek parametre değerlerini ve kimlik doğrulama bilgisini içeren bir kod parçacığı almak için, önce isteği gönderin, ardından kodu Gerçek İstek sekmesinden okuyun.
Önce tasarım yaklaşımıyla çalışıyorsanız, bu kolaydır. Uç noktayı Düzenle sekmesinde tanımlayın, Çalıştır sekmesine tıklayın ve istek parametreleri spesifikasyondan otomatik olarak dolar. Bunun yerine ayarları manuel olarak yapmak isterseniz (önce istek modu), istek parametrelerini Çalıştır sekmesine manuel olarak girin. Her iki durumda da, kimlik doğrulama belirtecinizi ekleyin, ardından isteği iletmek için Gönder'e tıklayın.
Yanıt geldikten sonra Gerçek İstek sekmesine geçin ve istemci kodunu bulmak için aşağı kaydırın. Şimdi oluşturulan kod parçacığı, gerçekten gönderilen somut değerleri ve kimlik doğrulama başlığını içeriyor:
import requests
url = "https://api.example.com/orders"
querystring = {"status": "shipped", "page": "1"}
headers = {
"Accept": "application/json",
"Authorization": "Bearer sk_live_51H8xY2..."
}
response = requests.get(url, headers=headers, params=querystring)
print(response.json())
İki yol arasındaki fark budur. Önce tasarım modu, parametreleri spesifikasyondan otomatik olarak doldurur; önce istek modu ise bunları sizin yazmanıza izin verir. Her ikisi de Gönder'e tıkladığınızda aynı Gerçek İstek kod parçacığını besler. Yukarıdaki gibi gerçek bir belirteci bir sır olarak kabul edin ve git'e taahhüt ettiğiniz hiçbir şeyin dışında tutun; Stripe'ın belgelerinin canlı anahtarlar için tavsiye ettiği özen burada da geçerlidir.
POST ve PUT için istek gövdelerini işleme
GET /orders bir gövdeye sahip değildir, ancak bir POST /orders veya PUT /orders/{id} için kod oluşturduğunuz anda, kod parçacığında bir istek gövdesine ihtiyacınız olur. Apidog, oluşturmadan önce Çalıştır sekmesinde bir tane oluşturmanıza yardımcı olur.
JSON veya XML gövdeleri için iki kaynağınız vardır. Uç nokta spesifikasyonundan önceden tanımlanmış bir örnek kullanın veya şemanızla eşleşen bir gövde yapısı oluşturmak için Otomatik Oluştur'a tıklayın. Otomatik Oluştur açılır menüsü size iki mod sunar:
- Örnekler: önceden tanımlanmış bir istek gövdesi örneğini manuel olarak seçin.
- Her Seferinde Oluştur: her kullanımda veriyi yeniden oluşturur, akıllı taklit kurallarına uyarak her seferinde yeni, şemaya uygun değerler elde etmenizi sağlar.
Verilerin nasıl üretildiğini Otomatik Oluşturma Tercihi alt seçenekleri aracılığıyla yönlendirebilirsiniz: Örnek Değerleri Önce Kullan, Varsayılan Değerleri Önce Kullan, Taklit Değer Kullan, Yalnızca Alan Adlarını Oluştur ve İstek Örneğini Kullan. Spesifikasyonunuz iyi örneklere sahip olduğunda ve bunların dikkate alınmasını istediğinizde Örnek Değerleri Önce Kullan'ı seçin; her alan için gerçekçi oluşturulmuş veri istediğinizde Taklit Değer Kullan'ı seçin.
Bir sürüm notu: istek gövdeleri için Otomatik Oluştur seçenekleri Apidog 2.7.0 veya sonraki bir sürümünü gerektirir. Eğer bunları görmüyorsanız, uygulamayı güncelleyin. OpenAPI'dan API belgelerini otomatik oluşturmaktan elde ettiğiniz türden, örneklerle iyi belirtilmiş bir şema, bu adımda neredeyse hiç manuel düzenleme yapmadan temiz gövdeler üretmenizi sağlar.
Her istekte değişen bir değere ihtiyacınız olduğunda, örneğin yeni bir zaman damgası veya rastgele bir sipariş kimliği gibi, sabit kodlama yerine dinamik bir değer ekleyin. Bir parametre giriş kutusunun yanındaki sihirli değnek simgesine tıklayın veya bir JSON veya XML istek gövdesinin içindeki Dinamik Değer Ekle düğmesini kullanın. Gövde hazır olduktan sonra Gönder'e tıklayın, ardından bitmiş kod parçacığını daha önce olduğu gibi Gerçek İstek sekmesinden okuyun.
İstek kod parçacığını ne zaman kullanmalı, iş modeli çağrısını ne zaman kullanmalı
Hızlı bir değerlendirme: ne kadar kod kopyalamalısınız?
Tek seferlik bir işlem yaparken tek bir istek kod parçacığına (cURL, fetch, yalın bir requests.get) başvurun. Bir uç noktanın neden 403 döndürdüğünü ayıklarken, bir bilete yeniden üretilebilir bir çağrı paylaşırken, terminalde hızlı bir kontrol yaparken veya kendi belgelerinize bir örnek yapıştırırken. Bu kod parçacığı bağımsızdır ve herhangi bir çevreleyici yapıya ihtiyaç duymaz.
Çağrı gerçek uygulama mantığı içinde yer alıyorsa, daha eksiksiz, iş modeli tarzı koda (başlıklar, parametreler ve yanıt işleme ile birlikte düzenlenmiş Axios veya requests bloğu) yönelin. Eğer GET /orders üç yerden çağrılan bir servis modülünde bulunacaksa, bir fonksiyon içine sarabileceğiniz, hata işleme ekleyebileceğiniz ve yeniden kullanabileceğiniz yapılandırılmış versiyonu istersiniz. Oluşturucu, seçtiğiniz varyanta bağlı olarak her iki şekli de sunar; kodu nerede yaşayacağına uygun şekli seçin.
Tüm bir projede aynı uç noktaları aynı kimlik doğrulama ile çağırıyorsanız, paylaşılan parçaları merkezileştirmek genellikle daha temizdir. Apidog'da genel parametreleri ayarlama kılavuzumuz, başlıkları ve değişkenleri bir kez nasıl tanımlayacağınızı gösterir, böylece her oluşturulan çağrı, belirteci her kod parçacığında tekrarlamak yerine bunları devralır.
Oluşturulan kodu önce spesifikasyon alışkanlığıyla doğru tutun
Oluşturulan kod, arkasındaki spesifikasyon kadar doğrudur. GET /orders çağrısını bir region sorgu parametresi eklemek için değiştirir ve yeniden oluşturmayı unutursanız, kopyalanan kod parçacığınız sessizce yanlış olacaktır. Çözüm, spesifikasyonu sürdürdüğünüz şey olarak, kodu ise talep üzerine yeniden oluşturduğunuz türetilmiş bir çıktı olarak ele almaktır. Apidog'un önce spesifikasyon modu, tanımı yetkili kılar, böylece oluşturduğunuz istek kodu her zaman güncel sözleşmeyi yansıtır, eski birini değil.
Kod parçacıklarının sözdizimi için, Apidog'un ürettiği JavaScript varyantlarını anlamak veya değiştirmek istediğinizde Fetch API hakkındaki MDN belgeleri sağlam bir referanstır.
İş akışını Apidog CLI ile otomatikleştirin
Kod oluşturma başlı başına bir GUI eylemidir; bir panelden bir kod parçacığını kopyalarsınız ve istemci kodu yayan ayrı bir CLI komutu yoktur. Apidog CLI'nin iyi yaptığı şey, oluşturmanın bağlı olduğu iki şeyi korumaktır: güncel bir spesifikasyon ve oluşturulan istemcinin gerçekten çalıştığını kanıtlayan geçen testler.
npm install -g apidog-cli (Node.js v16+) ile kurun ve kimlik doğrulaması yapın:
apidog login --with-token <YOUR_ACCESS_TOKEN>
Oluşturduğunuz kodun güncel kalması için yeni spesifikasyon değişikliklerini içe aktarın ve istemcinizin çağırdığı uç noktayı test eden kaydedilmiş test senaryosunu çalıştırın:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Burada -t test senaryosu kimliği, -e ortam kimliği ve -r raporlayıcıdır (cli, html veya junit). Bunu işlem hattınıza, Apidog CLI GitHub Actions kılavuzumuzun belirttiği şekilde entegre edin ve her bir gönderim, GET /orders'ın spesifikasyonun vaat ettiği gibi davrandığını, kimse ondan yeni bir istemci oluşturmadan önce doğrular. CLI istemci kodunuzu yazmaz, ancak bu kodun üzerine inşa edildiği sözleşmeyi korur.
Sıkça Sorulan Sorular
Oluşturulan kod API anahtarımı ve belirtecimi içeriyor mu?
Varsayılan olarak hayır. Yalnızca API spesifikasyonundan oluşturulan kod, yalnızca spesifikasyonu içerir, gerçek parametre değerlerini veya kimlik doğrulamasını değil. Gerçek belirtecinizi ve değerlerinizi içeren bir kod parçacığı almak için, önce isteği gönderin, ardından kodu Gerçek İstek sekmesinden okuyun. O kod parçacığındaki herhangi bir belirteci bir sır olarak kabul edin.
Apidog hangi diller ve kütüphaneler için kod oluşturabilir?
Geniş bir yelpaze. Shell (cURL, Httpie, wget, PowerShell), JavaScript (Fetch, Axios, jQuery, XHR ve daha fazlası), Python (http.client ve Requests), Java (Unirest, OkHttp), Go, PHP, Swift, C, C#, Ruby, Dart, R ve diğerleri. Oluşturucu panelinde dili ve belirli varyantı seçersiniz.
İstek gövdeleri için Otomatik Oluştur seçeneklerini neden göremiyorum?
Bu seçenekler Apidog 2.7.0 veya sonraki bir sürümünü gerektirir. Uygulamayı güncelleyin ve bir JSON veya XML gövdesi oluşturduğunuzda Çalıştır sekmesinde görüneceklerdir. Kullanıma sunulduğunda, Otomatik Oluştur açılır menüsü Örnekler ve Her Seferinde Oluştur seçeneklerini sunar, ayrıca değerlerin nasıl üretileceğine dair tercih alt seçenekleri bulunur.
İstemci kodu oluşturma ücretli bir özellik mi?
Apidog belgeleri, istemci kodu oluşturma için ücretsiz-ücretli veya bulut-kendi kendine barındırılan bir ayrım yapmamaktadır. Herhangi bir yerde bahsedilen tek sürüm gereksinimi, Otomatik Oluştur istek gövdesi seçeneklerinin 2.7.0 veya sonraki bir sürümünü gerektirmesidir. Apidog'u indirebilir ve ücretli bir plan olmadan oluşturucuyu deneyebilirsiniz.
Oluşturulan çağrının gerçekten çalıştığından nasıl emin olurum?
Kod parçacığını oluşturun, ardından uç noktayı kaydedilmiş bir testle doğrulayın. Apidog ile bir test senaryosu yazma hakkındaki rehberimiz, nasıl oluşturulacağını gösterir ve CLI bunu CI'da çalıştırarak bozuk bir sözleşmenin, siz ondan yeni bir istemci oluşturmadan önce derlemeyi başarısız etmesini sağlar.
Özet
Apidog'da istemci kodu oluşturmak, bir uç nokta spesifikasyonunu çalıştığınız dilde yapıştırmaya hazır bir isteğe dönüştürür ve Gerçek İstek sekmesi, boş bir şablon yerine gerçek değerleri ve kimlik doğrulamasını bu kod parçacığına dahil etmenin püf noktasıdır. Spesifikasyonu yetkili tutun, değiştiğinde yeniden oluşturun ve kaydedilmiş bir testin çağrının hala çalıştığını onaylamasına izin verin. Devam etmek için Apidog'u indirin, GET /orders uç noktanızı tanımlayın ve birkaç tıklamayla çalışan bir istemci çağrısını kopyalayın.