Uyumluluk — PassportCraft API

Uyumluluk

v1 üzerinde haber vermeden neleri değiştirebileceğimiz ve neyin yeni bir ana sürüm gerektireceği. Söz vermek yerine madde madde sayıldı; böylece bir entegrasyon tam olarak doğru kümeye karşı savunmacı biçimde kurulabilir.

Yollar, yöntemler, kapsamlar, alan adları ve hata kodları İngilizce yayımlanır; çünkü arayüzün kendi dili İngilizcedir — çağrıyı yapanın yazdığı ya da eşleştirdiği şey budur. Aynısı her kod örneği, her JSON gövdesi ve bir hata yanıtının taşıdığı tam cümle için de geçerlidir: /v1, Accept-Language başlığını okumaz; API’nin gerçekte gönderdiğini çevirmek onu yanlış tanımlamak olurdu. Bunlar hakkında yazılan her şey bu sayfanın dilini izler.

Geçerli revizyon 2026-08-01. Yol /v1 olarak kalır; revizyon, onu betimleyen belgeyi tanımlar.

v1 üzerinde yapmayacağımız değişiklikler

Bunlar yeni bir ana sürüm gerektirir. Böyle bir sürüme ihtiyaç duyarsak, geçiş süresince mevcut sürümler yanıt vermeyi sürdürür.

Bir işlemin kaldırılması.
Bir parametrenin ya da yanıttaki bir alanın kaldırılması veya yeniden adlandırılması.
Yeni bir zorunlu parametre eklenmesi.
Daha önce isteğe bağlı olan bir parametrenin zorunlu hale getirilmesi.
Bir parametrenin ya da bir yanıt alanının türünün değiştirilmesi.
Bir enum'dan değer kaldırılması.Değere göre dallanan bir istemcide, o değerin yokluğu için bir dal yoktur; istemci de kendi dilinin ele alınmayan bir durumda başarısız olduğu biçimde başarısız olur.
Mevcut bir parametreye yeni bir doğrulama kuralı eklenmesi.Dün başarılı olan bir istek başarısız olmaya başlar; bu, hata düzeltmesi kılığına girmiş bir yetenek kaybıdır.
Kimlik doğrulama veya yetkilendirme gereksinimlerinin, bir işlemin istediği kapsam da dahil olmak üzere değiştirilmesi.

Her an yapabileceğimiz değişiklikler

Entegrasyonunuz bunların tamamına dayanıklı olmalıdır. Gerçekleşecekler ve duyurulmayacaklar.

Yeni bir işlem eklenmesi.
Yeni bir isteğe bağlı parametre eklenmesi.
Yeni bir isteğe bağlı istek başlığı eklenmesi.
Bir yanıta yeni bir alan eklenmesi.Yanıtları hoşgörülü biçimde ayrıştırın — bilinmeyen alanları reddeden bir istemci, ekleyeceğimiz ilk alanda kırılır.
Yeni bir yanıt başlığı eklenmesi.
Bir enum'a değer eklenmesi.Tanınmayan bir değeri hata olarak değil, varsayılan durum olarak ele alın. Yeni pasaport kategorileri ve yeni olay türleri ortaya çıkacaktır.
Bir hata kodunun daha kesin kodlara bölünmesi — ancak yalnızca, özgün kodun yeniden deneme gibi bir çalışma zamanı mantığıyla çözülemediği yerlerde.Bir istemcinin ÜZERİNDE DALLANDIĞI bir kodu bölmek uyumu bozar; yalnızca günlüğe yazdığı bir kodu bölmek bozmaz. Ayrım, davranışın o koda bağlı olup olmadığındadır.

İstemcinizin neye dayanıklı olması gerekir

Bunların her biri, yukarıda kendimize saklı tuttuğumuz bir değişikliğe karşılık gelir. Birini ihlal eden bir istemci, bizim sıradan saydığımız bir değişiklikte kırılır.

Tanımadığınız yanıt alanlarını, yanıtın tamamını reddetmek yerine yok sayın.
Tanınmayan bir enum değerini hata olarak değil, varsayılan durum olarak ele alın.
Tanımlayıcıları içeriği okunmayan dizgeler olarak değerlendirin; onları hiçbir zaman ayrıştırmayın ve bir desene göre eşleştirmeye çalışmayın.
Bir JSON nesnesindeki alanların SIRASINA ya da insan tarafından okunan bir hata iletisinin tam ifadesine güvenmeyin. Bunun yerine makine tarafından okunabilen hata koduna göre dallanın.
429 yanıtında ve Retry-After başlığı taşıyan diğer her rette, başlıkta belirtilen süreyi bekleyerek yeniden deneyin. Bu başlık yalnızca 429’a özgü değildir: 409 resource_busy, 503 storage_unavailable ve 503 entitlement_unavailable yanıtları da taşır, çünkü orada çözüm yeniden denemektir.
Bir 5xx yanıtını YENİ bir Idempotency-Key ile yeniden deneyin. Sunucu hatası kaydetmiş bir anahtar, saklama süresi boyunca aynı hatayı yeniden oynatır — bu bilinçlidir; çünkü başarısızlık, aslında BAŞARILI olmuş bir yazma işlemine ait kaybolmuş bir yanıt olabilir ve başarısız tek bir yazma işleminin ikiye çıkmasını önleyen şey, anahtarın yeniden kullanılmasıdır.
Deprecation ve Sunset yanıt başlıklarını ve bunların taşıdığı Link: rel="successor-version" değerini izleyin. Bir uç noktanın kaldırılacağı böyle duyurulur ve bu duyuru, uç nokta yanıt vermeyi bırakmadan çok önce gelir.

Her tanımlayıcıyı, en fazla 255 karakterlik, içeriği okunmayan bir dizge olarak değerlendirin. Onları ayrıştırmayın, biçimlerini doğrulamayın ve UUID olduklarını varsaymayın — biçim haber verilmeden değişebilir.

Kullanımdan kaldırma

Kaldırılması planlanan bir uç nokta, Deprecation ve Sunset başlıklarıyla ve haleflerini adlandıran bir Link başlığıyla yanıt verir. Bunlar, uç nokta yanıt vermeyi bırakmadan çok önce gelir. Bu başlıkları izleyin.