REST API'lerini sürümleme. Her API'nın kendi sürümü vardır

URL'de REST API'lerinin sürümünü, özellikle yolun başlangıcında, yani aşağıdaki gibi bir şey belirtmek çok yaygındır:

POST /api/v1/accounts
GET /api/v1/accounts/details

Ancak, sürümün her API ile ilişkili olduğu herhangi bir tasarım görmedim. Başka bir deyişle, her bir API'nın sürümünü ayrı tutuyoruz. yani:

POST /api/accounts/v2
GET /api/accounts/details/v3

Bu yaklaşımı kullanarak, değişikliği bozulduğunda belirli API'nın API sürümünü artırıyoruz, tüm API'ların sürümünü artırmaya gerek yok.

Ortak stil yerine bu stili kullanmanın sakıncaları nelerdir?

— Eng.Fouad
kaynak

Yanıtlar:

Ne diyoruz tek REST API'leri DİNLENME API olarak adlandırabileceğimiz kaynakların belirli seti veya kaynakların . Ayrıca REST API'nin işlevleri olarak da bakabilirsiniz . Her tür yazılım gibi, tüm paket tek işlevler veya kaynaklar değil, sürümlendirilir / güncellenir.

Sorunuz, REST API paketinin kaynaklarının modüler olduğu ve potansiyel olarak ayrı ayrı geliştirildiği ve sürümlendirildiği bağlamda anlamlı olacaktır.

Daha sonra, gördüğüm kadarıyla, önerilen kaynak bulucu adlandırma kuralınızın ana eksileri:

İçin API kullanıcısı , bu daha az tahmin edilebilir az unutulmaz ve az stabil çok daha karmaşık kaynak bulma araçları olmasına neden olur.
İçin modül geliştirici (ler) , daha fazla iş bu sürüm ile uğraşmak zorunda şimdi var kendi kaynak bulucu.
Kaynak konumlandırıcılarındaki değişiklikler, birden fazla modülün güncellenmesi kadar çok daha sıklaşır, bu nedenle yukarıdaki eksiler üsteldir ...

Bir API oluştururken, ana hedeflerinizden biri kullanımı kolaylaştırmaktır ...

Bir HTTP değişikliği ile REST API'sını bozmak veya hatta sürümlendirmek için daha iyi bir yol bulabilirsiniz?

HTTP üstbilgileri yaklaşımı hakkında biraz daha fazla bilgi için, aşağıdaki diğer yanıtlara bakın ve: https://www.troyhunt.com/your-api-versioning-is-wrong-which-is/

— ClemC
kaynak

İşte daha da iyi bir yaklaşım: API'nizi ve başlıklarıyla sürümlendirmek için içerik pazarlığını kullanın :Content-TypeAccept

POST /api/accounts
Accept: application/vnd.my-api.account.v1+json

201 Created
Location: /api/accounts/285728
Content-Type: application/vnd.my-api.account.v1+json
{ ... account data here ... }

Farklı bir sürüm elde etmek için yalnızca farklı içerik türünde bir içerik isteyin Accept. Bu şekilde, sunucunuzun desteklediği belirli sürümler URL yapınızdan tamamen bağımsızdır. Aynı sunucu, Acceptbaşlığa bağlı olarak yanıt vermeyi seçerek birden çok sürümü destekleyebilir . Alternatif olarak, farklı sürümler için farklı dağıtımlara sadık kalmak istiyorsanız, hizmetinizin farklı sürümlerinin önüne, hangisini Acceptbaşlığa göre istek ileteceğini belirten bir proxy yerleştirebilirsiniz .

Bu , aynı uç noktalarda farklı semantiklere (yalnızca farklı sürümlere değil) sahip yeni formatları desteklemenizi sağlar . Örneğin, bir hesap listesini POST yapmak /api/accountstoplu oluşturma anlamına gelebilir ve bunun için ayrı bir API uç noktası oluşturmanız gerekmez.

— kriko
kaynak

omg kabul başlığı sürüm sinyallemesinin en kötü tercihi olmalıdır. mümkünse bir sürüm üstbilgisi kullanın, gerekirse URL yolu (örn. AWS yönlendirme)

— Ewan

@Ewan Neden? Özel bir sürüm başlığı, aracılara içeriğin farklı olabileceğini bildirmeden farklı sürümlerin aynı kaynak olduğunu ima eder. Önbellek proxy'si, v2 isteklerine v1 önbelleğe alınan yanıtlar sunmak için başlığınızı kullanamaz.

— Jack

API istekleri için önceden önbellek kullanmıyorsanız, değişiklik yanıtı başlığını kullanın !. içerik türünün zaten bir anlamı var, özel kullanımınız için altını oymak tüketiciler için hayatı zorlaştırıyor

— Ewan

@Ewan Türün vndparçası ve +sözdizimi bunun içindir: bunun türün satıcıya özgü bir alt türü olduğunu belirtmek için application/json. İçerik türleri tam olarak bunun için tasarlanmıştır. Kaynağınız birden çok biçimde kullanılabilir. Müşteriden istedikleri biçimi seçmesini istersiniz. Ayrıca, API isteklerinin standart HTTP önbellek semantiği kullanamamasının bir nedeni yoktur.

— Jack

myapi v2'de bir hatayı düzeltirseniz, yeni bir mime türü döndürmezsiniz.

— Ewan

Önemli olan, her uç noktayı ayrı ayrı sürümlendirmeniz durumunda, her uç noktayı ayrı ayrı dağıtabilmenizdir.

API'lerin genellikle bir sürümü vardır, çünkü tüm uç noktalar aynı kod tabanındadır ve bu nedenle paylaşılan bağımlılıklar vardır ve birlikte dağıtılır.

Eğer bir değişiklik yaptığınızda sürümü güncellemiyorsanız, çünkü "Oh, yaptığım değişikliğin bunu etkilemediğine eminim."

Ayrıca, API'nızın hem v1 hem de v2'sinin aynı anda dağıtılmasını istersiniz. Bu normalde her sürümü ayrı bir sunucuya dağıtarak ve trafiği buna göre yönlendirerek yapılır.

Tek bir API sürümünüz yoksa, bu çok daha karmaşık hale gelir.

— Ewan
kaynak