Sonlu seçenek kümesine ekleme; API kırılma değişikliği?

9

Aşağıdaki yanıt modelini veren bir HTTP API uç noktası alın:

{
    "type": "Dog",
    "name": "Jessi",
    ...
}

typeAlan biri olarak belgelerinde tarif edilmiştir Dog, Catya da Fish.

Yeni bir seçenek eklemek, örneğin Rat, bir API değişikliği olarak kabul edilir mi?

Sonlu bir listeye (bir geliştiricinin açabileceği) bir seçenek eklemek bir API'da uzantı veya değişiklik olarak mı kabul edilir?

— Dave Yeni
kaynak

10

Belgeler bu alanı Köpek, Kedi veya Balık olarak tanımladıysa, evet, başka bir tür eklemek arabirimi geriye doğru uyumsuz bir şekilde değiştirir. API'nızın bir tüketicisinin köpeklerle ve kedilerle balıktan farklı bir şekilde başa çıkmak için belirli bir kod yazdığı tamamen düşünülebilir. Bilinmeyen bir tür verildiğinde, bu tüketici yanıtınızla ne yapacağınızı bilemez. Ancak bu büyük ölçüde bu yer tutucu türlerinin "Kedi" ve "Balık" ın gerçek sorun alanınızda neyi temsil ettiğine bağlıdır ...

Olası türler listesindeki değişiklikler sıksa veya liste sonlu değilse, bu şekilde belgelemek mantıklıdır. Kullanım durumlarınıza bağlı olarak, tüm olası türlerin bir listesini API'nızda bir son nokta olarak göstermek iyi olabilir - bu şekilde API sürümünü güncellemek zorunda kalmadan tür ekleyebileceğiniz veya kaldırabileceğiniz açıktır. Bununla birlikte, türleriniz ne kadar dinamik olursa, API tüketicilerinin türe özgü bir şey yapmaları o kadar zorlaşır. Genişletilebilirliğin veya kullanım kolaylığının daha önemli olup olmadığı kullanım durumlarınıza ve sorun alanınıza bağlıdır.

— amon
kaynak

Harika cevap - teşekkürler. Belgeler, "aşağıdaki tabloda API tarafından şu anda desteklenen hayvanlar" başlıklı bazı tablolardaki seçenekleri ayrıntılı olarak belirtirse ne olur? Bu seçeneklerin genişletilebileceğini göstermiyor mu?

— Dave New

1

@davenewza Bu muhtemelen iyi bir fikir ama daha açık olurdum. Sadece etmeyin işaret ne demek - doğrudan söylemek! Açıkça beklentiler belirlemeye ve bu uç nokta için dokümanlarda bir istikrar garantisi sunmaya çalışacağım : “Aşağıdaki tablo şu anda desteklenen hayvanları listeliyor, ancak gelecekte desteklenen hayvanlar ekleyebilir veya kaldırabiliriz. Bu olduğunda, API'nın küçük sürüm numarasını güncelleyeceğiz. ”

— amon

Yürütülebilir özellikler >>> belgelenmiş özellikler >>> belgelenmemiş özellikler.

— VoiceOfUnreason

0

Yalnızca "Sıçan" mevcut işlemlerden döndürülebilseydi kırılabilirdi.

Mevcut işlemler "Rat" döndüremezse, bu yeni seçeneğin eklenmesinin hiçbir etkisi olmaz.

— Jon Raynor
kaynak