İstek ve Yanıt Biçimi

2k görüntülenme Markdown

Her adresin her ucunda tek bir zarf, tek bir durum kodu kümesi ve tek bir sayfalama biçimi.

Genel Bakış

Bir çağrının biçimi kaynaktan kaynağa değişmez. Bir yanıtı okuyabiliyorsanız hepsini okuyabilirsiniz; bir kez yazılan hata yönetimi entegrasyonunuz büyüdükçe çalışmaya devam eder.

İşin çoğunu iki kural taşır. Başarılı yanıt içeriğini data altına koyar, başarısız olan ise makine tarafından okunabilir bir kodu error altına koyar. HTTP durumu her zaman hangisinin geldiğiyle uyuşur.

Referans

İstek

JSON'u Content-Type: application/json başlığıyla gönderin. Form kodlu POST da kabul edilir; istemci başlığı kuramıyorsa bu işe yarar. Süzgeç, sıralama ve sayfalama her metotta sorgu dizesinde taşınır.

Authorization: Bearer API anahtarı. Bunu kuramayan istemciler için yedek başlık X-Api-Key.

Content-Type Gövde JSON ise application/json verin. Vermezseniz gövde form alanı olarak okunur.

Idempotency-Key İsteğe bağlı, yalnız POST, 8 ile 191 karakter. Aynı anahtarın tekrarı, işi ikinci kez yapmak yerine saklanan yanıtı döndürür. Sunucu hatası da saklanır: 500'den sonra işi yeniden çalıştırmak için yeni bir anahtar gönderin.

X-Http-Method-Override Yalnızca GET ve POST'a izin veren bir vekil sunucunun arkasındaki çağıranlar için. POST ile gönderildiğinde değer metodun yerine geçer; başka bir metotta başlık yok sayılır, yani GET, GET olarak kalır.

Açık/kapalı bir alan JSON boolean değerini, 1 ya da 0 sayısını kabul eder. Şu yazı biçimleri de geçerli: true ve false, on ve off, yes ve no; büyük/küçük harf ayrımı yok. Form kodlu gövde ve sorgu dizesi her değeri yazı olarak taşır. enabled=false alanı orada da JSON false gibi kapatır. Boş değer kapalı sayılır. Başka her yazı, dizi ya da nesne 422 ve invalid_<field> koduyla reddedilir. details.field alanı adlandırır, hiçbir şey yazılmaz. Bir ucun kendi makalesi daha dar bir küme belirtiyorsa o geçerlidir. Bu, 0 ya da 1 olarak belgelenen alanları ve yalnız JSON boolean alan müşteri uçlarını kapsar.

Zarf

Başarı data taşır; içerik hakkında söylenecek bir şey varsa yanında meta gelir. Başarısızlık ise sabit bir code, insanın okuyacağı bir mesaj ve doğrulama hatalarında alanları adıyla veren bir details eşlemesi taşır.

iki biçim

{ "data": { "id": 42, "email": "[email protected]" } }

{ "data": [ ], "meta": { "total": 318, "page": 2, "limit": 25, "next_page": 3 } }

{ "error": { "code": "validation_failed", "message": "Email is not valid.",
             "details": { "email": "invalid_format" } } }

Metne göre değil anahtara göre dallanın. code sözleşmenin parçası ve yerinde kalır; message kayıt okuyan bir insan için yazılmıştır ve yeniden ifade edilebilir.

Durum Kodları

200 · 201 Tamam. Oluşturma 201 ile cevap verir ve yeni kaydı döndürür.

401 Anahtar yok ya da kurulumun tanımadığı bir anahtar. Kimlik bilgisini düzeltin; yeniden denemek işe yaramaz.

403 Anahtar tanınıyor ama buraya izinli değil: yanlış adres, eksik izin ya da demo kipi açıkken yazma denemesi.

404 Böyle bir uç yok ya da bu anahtar için böyle bir kayıt yok. Müşteri adresinde başkasına ait kayıt da aynı cevabı alır.

409 Aynı Idempotency-Key ile bir istek hâlâ sürüyor. Bekleyip yeniden deneyin.

413 Gövde sunucunun yükleme sınırını aştı. Kaynağa hiç ulaşmadı, dolayısıyla hiçbir şey kaydedilmedi.

422 Girdi anlaşıldı ve reddedildi. details alanları adıyla verir.

429 Çok fazla istek. Retry-After süresine uyun.

500 Karşı tarafta bir şey hata verdi. Ayrıntı yanıtta değil, operatörün hata kaydında durur.

Sayfalama

Liste uçları sorgu dizesinde page ve limit alır. limit varsayılan 25, tavanı 100; daha fazlasını istemek sessizce 100 verir. Sayfaları meta.next_page ile gezin; son sayfada değeri 0 olur.

Kaydırma tabanlı sayfalama v1 sözleşmesidir. İmleç tabanlı sayfalama yalnız veri bir zaman akışı olduğunda kullanılır, örneğin talep mesajlarında; o uçlar kendi imleç alanlarını kendileri anlatır.

Yanıt Başlıkları

Kimlik isteyen her yanıt bütçenizin durumunu bildirir, böylece tahminle değil ölçerek hız ayarlarsınız.

X-RateLimit-Limit Bu dakikalık pencerede izin verilen istek sayısı.

X-RateLimit-Remaining Ondan geriye kalan.

X-RateLimit-Reset Pencerenin yenileneceği an, Unix zamanı olarak.

Idempotency-Replayed Yanıt taze işten değil kayıttan geldiğinde bulunur.

Örnek

güvenle tekrarlanabilir bir yazma

curl -X POST 'https://panel.example.com/api/v1/admin/clients' \
     -H 'Authorization: Bearer wak_...' \
     -H 'Content-Type: application/json' \
     -H 'Idempotency-Key: signup-8f21c0' \
     -d '{"name":"Ada","surname":"Lovelace","email":"[email protected]"}'
# 201  {"data":{"id":91,...}}

# aynı çağrı tekrar aynı gövdeyi döndürür ve ikinci bir müşteri oluşturmaz
# 201  Idempotency-Replayed: true

Tuzaklar

Toplamlar kökte değil meta altında

Liste yanıtı sayısını meta.total içinde tutar. total değerini kökten okumak size hiçbir şey vermez ve hata da üretmez; sonuç boş bir küme gibi görünür. Aynısı page ve limit için de geçerli.

Demo kipi her yazmayı reddeder

Kurulum demo kipindeyken POST, PUT, PATCH ve DELETE herhangi bir kaynağa ulaşmadan 403 demo_mode ile döner. Okumalar çalışmaya devam eder, demo API üzerinden gezilebilir kalır. Yalnızca yazmalarda hata veren bir entegrasyonda önce buraya bakmaya değer.

Faydalı oldu mu?

Geri bildiriminiz için teşekkürler!

Hâlâ Yardıma mı İhtiyacınız Var?

Yukarıda bulamadığınız her şey için destek ekibimiz her zaman yanınızda.

Bize Ulaşın Destek Talebi Oluştur