Apidog'da API Spesifikasyonundan İstemci Kodu Nasıl Oluşturulur

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 ve sorgu parametreleri tek bir requests veya fetch çağrısında birleşmelidir. Tek bir karakteri yanlış kopyalamak bile 401 gibi hataları ayıklamak için gereksiz zaman kaybetmenize neden olabilir.

Apidog'u bugün deneyin

Bu kalıp kodu elle yazmak zorunda değilsiniz. API'niz Apidog'da tasarlandıysa, platform uç nokta spesifikasyonunu okuyarak yapıştırmaya hazır istek kodu üretir:

• Terminal kontrolleri için cURL
• Betikler için Python requests
• Ön uçlar için JavaScript fetch veya Axios

Bu rehberde gerçek bir uç noktadan kod oluşturmayı, gerçek kimlik doğrulama ve parametre değerlerini içeren kodu ne zaman almanız gerektiğini ve spesifikasyon değiştikçe üretilen kodu güncel tutmayı göreceksiniz. Daha geniş araç seçenekleri için API kod oluşturma araçları derlemesine de bakabilirsiniz.

Bu yaklaşım, spesifikasyonun tek doğruluk kaynağı olması prensibine dayanır. Bu, OpenAPI Spesifikasyonu arkasındaki temel ilkelerden biridir: tanımı bir kez doğru yapın, istek kodu da bu tanımı takip etsin.

İstemci kod oluşturucu ne yapar?

Apidog, bir uç nokta tanımını seçtiğiniz dil ve HTTP kütüphanesi için bir istek kod parçacığına dönüştürür.

Örneğin GET /orders uç noktasını seçip Python ve Requests varyantını belirlediğinizde, Apidog spesifikasyondaki yol, başlık ve parametrelere uygun bir çağrı üretir.

Bu özellik bir istek oluşturucudur. Tam bir SDK veya sürümlü istemci kütüphanesi üretmez. Yani aşağıdakileri hızlıca alabilirsiniz:

• Tek satırlık cURL komutu
• Python requests bloğu
• JavaScript fetch kodu
• Axios çağrısı

Ancak modeller, sayfalama yardımcıları ve tür atanmış sınıflarla birlikte indirilebilir bir SDK beklemeyin.

Bu iş akışı, önce tasarım API geliştirme yaklaşımıyla doğrudan uyumludur:

1. API sözleşmesini tanımlayın.
2. İstek kodunu sözleşmeden üretin.
3. Her tüketicinin aynı güncel tanımdan başlamasını sağlayın.

Oluşturucuyu açmanın iki yolu

Apidog, istemci kodu oluşturucuya iki noktadan erişim sağlar.

1. Belgeler sekmesinden

Bir uç noktanın belgelerini incelerken kod almak için:

1. API'nizin Belgeler sekmesini açın.
2. İlgili uç noktayı seçin.
3. Sağ taraftaki İstemci Kodu Oluştur düğmesine tıklayın.

Bu yol, bir uç noktanın dokümantasyonunu okurken hızlıca örnek çağrı almak için uygundur.

2. Çalıştır sekmesinden

Bir isteği test ederken kod almak için:

1. API'nin Çalıştır sekmesini açın.
2. Kod simgesine, yani </> düğmesine tıklayın.
3. Dil ve HTTP kütüphanesi varyantını seçin.

Her iki giriş noktası da aynı oluşturucu panelini açar.

GET /orders için Python istemci çağrısı oluşturma

Aşağıdaki örnekte müşterinin siparişlerini listeleyen, duruma göre filtreleyen ve sayfalama kullanan bir GET /orders uç noktası üzerinden ilerleyelim.

Adım 1: Uç noktayı açın ve hedef dili seçin

Uç noktanın Belgeler sekmesini açın ve İstemci Kodu Oluştur seçeneğine tıklayın.

Apidog'da kullanabileceğiniz bazı dil ve varyantlar şunlardır:

• 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 ve ham HTTP

Bu örnekte Python ve Requests seçin. Spesifikasyona göre aşağıdaki gibi bir çağrı oluşturulur:

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())

Kod parçacığını betiğinize yapıştırabilir ve uç noktayı çağırabilirsiniz. Üretilen kod, tanımladığınız uç noktanın yolunu, parametrelerini ve başlıklarını yansıtır.

Adım 2: Spesifikasyondan gelen kodun sınırını anlayın

Yalnızca API spesifikasyonundan üretilen kod şu bilgileri içerir:

• HTTP metodu
• URL ve yol parametreleri
• Tanımlı başlıklar
• Sorgu parametreleri
• Spesifikasyondaki örnek değerler

Ancak gerçek istek parametreleri veya canlı kimlik doğrulama belirteciniz varsayılan olarak bu kodda yer almaz.

Örneğin korumalı bir uç nokta için aşağıdaki başlık spesifikasyondan oluşturulan boş şablonda bulunmayabilir:

Authorization: Bearer <gerçek-belirteç>

Kimlik doğrulaması gerektirmeyen çağrılar veya belirteci kendiniz ekleyeceğiniz durumlar için bu yeterlidir. Gerçek değerleri içeren kod istiyorsanız isteği önce çalıştırmalısınız.

Adım 3: Gerçek değerleri almak için isteği gönderin

Gerçek parametreler ve kimlik doğrulama bilgisiyle kod üretmek için aşağıdaki akışı kullanın:

1. Uç noktayı Düzenle sekmesinde tanımlayın.
2. Çalıştır sekmesine geçin.
3. Parametreleri kontrol edin veya gerekiyorsa manuel olarak girin.
4. Kimlik doğrulama belirtecini ekleyin.
5. Gönder düğmesine tıklayın.
6. Yanıt geldikten sonra Gerçek İstek sekmesine geçin.
7. Oluşturulan istemci kodunu aşağı kaydırarak bulun.

Örneğin gerçek bir Bearer belirteciyle gönderilen istekten sonra kod şu biçimde olabilir:

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 mod arasındaki temel fark şöyledir:

Mod	Parametrelerin kaynağı
Önce tasarım	Parametreler spesifikasyondan otomatik dolar
Önce istek	Parametreleri Çalıştır sekmesinde siz girersiniz
Gerçek İstek	Gönderilmiş istekteki somut değerleri ve başlıkları gösterir

Gerçek belirteçleri sır olarak değerlendirin. Bunları Git'e taahhüt etmeyin ve kaynak koduna sabit yazmayın. Stripe'ın canlı anahtarlarla ilgili önerileri bu konu için iyi bir referanstır.

POST ve PUT istek gövdelerini yönetme

GET /orders bir istek gövdesi gerektirmez. Ancak POST /orders veya PUT /orders/{id} gibi uç noktalar için gövdeyi de oluşturmanız gerekir.

Apidog'da bunu Çalıştır sekmesinden yapabilirsiniz.

JSON veya XML gövdeleri için iki temel seçeneğiniz vardır:

1. Uç nokta spesifikasyonundaki önceden tanımlı örneği kullanmak
2. Şemaya göre gövde oluşturmak için Otomatik Oluştur seçeneğini kullanmak

Otomatik Oluştur menüsünde şu modlar bulunur:

• Örnekler: Önceden tanımlı bir istek gövdesi örneğini seçmenizi sağlar.
• Her Seferinde Oluştur: Her kullanımda şemaya uygun yeni değerler üretir.

Değer üretimini Otomatik Oluşturma Tercihi seçenekleriyle yönlendirebilirsiniz:

• Örnek Değerleri Önce Kullan
• Varsayılan Değerleri Önce Kullan
• Taklit Değer Kullan
• Yalnızca Alan Adlarını Oluştur
• İstek Örneğini Kullan

Pratik seçimler:

• Spesifikasyonda gerçekçi örnekler varsa Örnek Değerleri Önce Kullan seçeneğini kullanın.
• Her alan için yeni ve gerçekçi test verileri istiyorsanız Taklit Değer Kullan seçeneğini kullanın.

İstek gövdeleri için Otomatik Oluştur seçenekleri Apidog 2.7.0 veya sonraki sürümleri gerektirir. Bu seçenekleri göremiyorsanız uygulamayı güncelleyin.

İyi tanımlanmış örnekleri olan bir OpenAPI şeması, manuel düzenleme ihtiyacını azaltır. Bunun için OpenAPI'dan API belgelerini otomatik oluşturma yaklaşımından yararlanabilirsiniz.

Zaman damgası veya rastgele sipariş kimliği gibi her istekte değişmesi gereken veriler için sabit değer kullanmayın. Bunun yerine:

• Parametre alanının yanındaki sihirli değnek simgesine tıklayın.
• JSON veya XML gövdesindeki Dinamik Değer Ekle düğmesini kullanın.

Gövde hazır olduğunda isteği gönderin ve tamamlanmış kodu Gerçek İstek sekmesinden alın.

İstek kod parçacığı mı, iş modeli çağrısı mı?

Kopyalayacağınız kodun biçimi, onu nerede kullanacağınıza bağlıdır.

Tek seferlik çağrılar için kod parçacığı kullanın

Aşağıdaki durumlarda tek bir cURL, fetch veya requests.get çağrısı yeterlidir:

• Bir 403 hatasını ayıklarken
• Bir bilete yeniden üretilebilir istek eklerken
• Terminalden hızlı kontrol yaparken
• Dokümantasyona kullanım örneği eklerken

Bu kod bağımsızdır ve ek proje yapısına ihtiyaç duymaz.

Uygulama mantığı için yapılandırılmış çağrı kullanın

Çağrı gerçek uygulama kodunda yaşayacaksa, onu tekrar kullanılabilir bir fonksiyon veya servis modülüne dönüştürün.

Örneğin GET /orders uygulamanın üç farklı yerinde çağrılıyorsa, temel kodu şu şekilde sarmalayabilirsiniz:

import os
import requests

BASE_URL = "https://api.example.com"
API_TOKEN = os.environ["API_TOKEN"]

def get_orders(status: str, page: int = 1) -> dict:
    response = requests.get(
        f"{BASE_URL}/orders",
        headers={
            "Accept": "application/json",
            "Authorization": f"Bearer {API_TOKEN}",
        },
        params={
            "status": status,
            "page": page,
        },
        timeout=30,
    )

    response.raise_for_status()
    return response.json()

Bu yapı sayesinde hata işleme, zaman aşımı, yapılandırma ve kimlik doğrulama mantığını tek bir yerde tutabilirsiniz.

Bir projedeki tüm uç noktalar aynı başlıkları veya kimlik doğrulama bilgisini kullanıyorsa, ortak değerleri merkezileştirin. Apidog'da genel parametreleri ayarlama rehberi, başlıkları ve değişkenleri bir kez tanımlayarak tekrarları azaltmayı açıklar.

Üretilen kodu spesifikasyonla güncel tutun

Üretilen kod, yalnızca arkasındaki spesifikasyon kadar doğrudur.

Örneğin GET /orders uç noktasına region adlı yeni bir sorgu parametresi eklerseniz, eski kod parçacığınız bu parametreyi içermez. Bu nedenle şu prensibi uygulayın:

1. Spesifikasyonu yetkili kaynak olarak tutun.
2. Uç noktayı değiştirdiğinizde kodu yeniden oluşturun.
3. Kopyalanmış kodu türetilmiş çıktı olarak kabul edin.
4. Güncel sözleşmeyi testlerle doğrulayın.

Apidog önce spesifikasyon modu, API tanımını yetkili kaynak olarak tutmanıza yardımcı olur.

JavaScript varyantlarını anlamak veya elle düzenlemek istiyorsanız, MDN Fetch API belgeleri güvenilir bir sözdizimi referansıdır.

İş akışını Apidog CLI ile otomatikleştirin

İstemci kodu oluşturma, GUI üzerinden yapılan bir işlemdir: panelden kod parçacığını kopyalarsınız. Ayrı bir CLI komutuyla istemci kodu üretilmez.

Bununla birlikte Apidog CLI, üretilen kodun dayandığı iki önemli şeyi korumanıza yardımcı olur:

• Güncel API spesifikasyonu
• Uç noktanın hâlâ çalıştığını doğrulayan test sonuçları

CLI'ı Node.js v16 veya üzeri sürümle kurun:

npm install -g apidog-cli

Ardından erişim belirteciyle giriş yapın:

apidog login --with-token <YOUR_ACCESS_TOKEN>

Kaydedilmiş bir test senaryosunu çalıştırmak için:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli

Parametreler:

• -t: Test senaryosu kimliği
• -e: Ortam kimliği
• -r: Raporlayıcı (cli, html veya junit)

Bu komutu CI işlem hattınıza ekleyin. Apidog CLI GitHub Actions rehberindeki yaklaşımı kullanarak, her gönderimde uç noktanın sözleşmeye uygun davranıp davranmadığını doğrulayabilirsiniz.

CLI istemci kodunuzu yazmaz; ancak bu kodun dayandığı API sözleşmesini test ederek korur.

Sıkça Sorulan Sorular

Oluşturulan kod API anahtarımı veya belirtecimi içerir mi?

Varsayılan olarak hayır. Sadece spesifikasyondan oluşturulan kod, gerçek parametre değerlerini veya canlı kimlik doğrulama bilgisini içermez.

Gerçek değerleri içeren bir kod parçacığı almak için:

1. İsteği Çalıştır sekmesinde hazırlayın.
2. Kimlik doğrulama bilgisini ekleyin.
3. İsteği gönderin.
4. Gerçek İstek sekmesindeki kodu alın.

Bu kodda bulunan tüm belirteçleri sır olarak değerlendirin.

Apidog hangi diller ve kütüphaneler için kod oluşturabilir?

Apidog; Shell, JavaScript, Python, Java, Go, PHP, Swift, C, C#, Objective-C, Ruby, Dart, R ve daha birçok hedef için kod üretebilir.

Örnek varyantlar:

• Shell: cURL, Httpie, wget, PowerShell
• JavaScript: Fetch, Axios, jQuery, XHR
• Python: http.client, Requests
• Java: Unirest, OkHttp
• PHP: cURL, Guzzle

Oluşturucu panelinden dil ve kütüphane varyantını seçebilirsiniz.

İstek gövdeleri için Otomatik Oluştur seçeneğini neden göremiyorum?

Bu seçenekler Apidog 2.7.0 veya sonraki sürümleri gerektirir.

Uygulamayı güncelleyin ve JSON veya XML gövdesi tanımladığınızda Çalıştır sekmesindeki Otomatik Oluştur menüsünü kontrol edin.

İ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 ayrımı belirtmez. Belgelerde belirtilen tek sürüm gereksinimi, istek gövdelerindeki Otomatik Oluştur seçenekleri için 2.7.0 veya sonraki sürüm gerekliliğidir.

Apidog'u indirebilir ve oluşturucuyu ücretli bir plan olmadan deneyebilirsiniz.

Oluşturulan çağrının gerçekten çalıştığından nasıl emin olurum?

Kod parçacığını oluşturduktan sonra uç noktayı kaydedilmiş bir test senaryosuyla doğrulayın.

Apidog ile test senaryosu yazma rehberi test senaryosu oluşturmayı açıklar. CLI ile bu testleri CI ortamında çalıştırarak, bozuk bir sözleşmenin derlemeye ulaşmasını engelleyebilirsiniz.

Özet

Apidog'da istemci kodu oluşturmak, uç nokta spesifikasyonunu kullandığınız dilde yapıştırmaya hazır bir isteğe dönüştürür.

Uygulanabilir akış şöyledir:

1. Uç noktayı tanımlayın.
2. Belgeler veya Çalıştır sekmesinden kod oluşturucuyu açın.
3. Dil ve HTTP kütüphanesi varyantını seçin.
4. Gerçek değerler gerekiyorsa isteği önce gönderin.
5. Kod parçacığını Gerçek İstek sekmesinden alın.
6. Spesifikasyon değiştiğinde kodu yeniden oluşturun.
7. Kaydedilmiş testleri CLI ve CI ile çalıştırın.

Başlamak için Apidog'u indirin, GET /orders uç noktanızı tanımlayın ve birkaç tıklamayla çalışan bir istemci çağrısı oluşturun.