API Sürüm Oluşturma Kılavuzu

API Sürüm Oluşturma

API tasarımı ve geliştirme, bir arka uç geliştirici için en önemli görevdir. Bir API geliştirilmiş ve kullanımda olsa bile, geliştiricilerin bilgi ve deneyimleri geliştikçe ve gereksinimler arttıkça, kullanım üzerinde değişiklikler kaçınılmazdır. Tehditler, müşterileriniz için mevcut entegrasyonu bozmayı içerdiğinden, bu zorlu bir sorun olabilir.

API sürüm oluşturma, bu sorunun en yaygın çözümlerinden biridir, ancak çoğu zaman geliştirme sürecinde sonradan düşünülür, ancak bir API tasarlamaya başlarken en önemli kısım olmalıdır.

Bu makalede, kullanıcı tüketimini ve esnekliğini kolaylaştırmak için API sürüm oluşturma için en iyi uygulamalardan bazılarını tartışacağız. Ancak, aklınıza gelebilecek ilk soru, API’lerinizi ne zaman sürümlendireceğinizdir. API sürüm oluşturma en iyi uygulamalarına geçmeden önce bunu ayrıntılı olarak tartışalım.

API’nizi ne zaman sürümlendirmelisiniz?

Herhangi bir yeni değişikliğin mevcut sistemi karmaşıklaştırması veya bozması ihtimali olduğunda API’lerin sürümlendirilmesi gerekir. Son değişiklikler aşağıdaki durumlardan herhangi birini içerebilir:

• Bir veya daha fazla API çağrısı için istek/yanıt biçiminde değişiklik
• İstek/yanıt içerik türünde değişiklik (ör. int’den float’a geçiş gibi veri türünde değişiklik)
• Herhangi bir eski uç noktayı kaldırma

Daha iyi anlamak için aşağıdaki hususları dikkate alın:

API sürümünüzü yayınlarsanız, kullanıcılar API çağrısının çıktısıyla ilgili herhangi bir soruna tanık olurlarsa, API sürümü oluşturma, yanıt verilerindeki değişikliği karşılamanıza ve bir sonraki sürümde kullanıcı geri bildirimlerini aşılamanıza yardımcı olabilir.

Herhangi bir eski uç nokta artık gerekli değilse ve haber verilmeden kaldırılırsa, bir kullanıcının onu vurmaya çalışması ve bir 404 hata durum koduyla uğraşmak zorunda kalması ihtimali vardır ki bu hiç kimse için pek eğlenceli değildir. Uygun API sürümü oluşturma, sizi ve kullanıcıyı tüm bu güçlüklerden kurtarabilir.

Yeni API uç nokta çağrısının, orijinal uç noktada gerekli olmayan ek bir anahtar gerektirdiği bir durum varsa, anahtar iletilmezse API’yi kırması zorunludur. Bu nedenle, yine kullanıcınızın başını belaya sokar. Ancak API sürümü oluşturma burada da size büyük zaman kazandırabilir.

Bunun gibi daha pek çok durum olabilir, ancak meselenin özü, geliştiricilerin sürekli değişen ve güncel API’lerinizi tüketmek için net ve özlü bir yola sahip olmalarını sağlamak için API’lerinizi her zaman sürümlendirmenin gerekli olmasıdır.

API’nizi nasıl sürümlendirirsiniz?

REST API’lerinin belirli bir API sürüm oluşturma yönergesi yoktur, ancak en yaygın yaklaşımlar aşağıdaki gibidir:

URI Sürüm Oluşturma

URI sürüm oluşturma tekniğini kullanmak, API’lerinizi sürümlendirmenin en basit ve en sık kullanılan yoludur. Bununla birlikte, bir URI’nin benzersiz bir kaynağa başvurması gerektiğini söyleyen önemli bir REST ilkesini ihlal ediyor. Şuna benziyor:

http//api.example.com/v1
http//apiv1.example.com

Burada v[x], x’in herhangi bir sayı olabileceği API sürümüdür. Ancak, sürümün bir sayı veya tam biçimde olması gerekmez.

Bu biçime alternatifler, API’leri geliştiren ekip için tarihleri, proje adlarını veya diğer anlamlı tanımlayıcıları içerir. Bunlar, sürümler değiştikçe değişebilecek kadar esnek, kısa ve öz olmalıdır.

Ayrıca, kullanıcının doğru belgelere başvurmasına yardımcı olur.

Özel İstek Başlıkları ile Sürüm Oluşturma

Aynı kaynağın veya içeriğin farklı sürümlerine hizmet etme yükü, istek başlıklarına göre gönderilecek kaynağın sürümünün belirlenmesinden sorumlu olacak API denetleyicisi veya sunucusu tarafından ele alınabilir.

Bu, kullanıcıların bir kaynak talep etmeden önce hangi başlıkların belirtilmesi gerektiğini bilmesi gerektiğinden, daha karmaşık bir API ile sonuçlanma eğilimindedir.

Özel istek başlıkları aracılığıyla API sürümü oluşturma aşağıdaki gibi görünebilir:

Accept: application/vnd.example.v1+json
Accept: application/vnd.example+json;version=1.0

Bu, gelen yükü anında ayrıştırabildiği için iyidir. Ancak bu yöntem, gecikmeye neden olabilecek bir yanıt göndermeden önce sürümü ayrıştırmak için sunucuda bir ek yük gerektirdiğinden yanıltıcı olabilir.

Sorgu Dizisi Parametresi

Sorgu dizelerini parametre olarak kullanarak API sürümü şöyle görünür:

http://api.example.com/:foo?version=v2

Bu, API sürüm oluşturma için iyi bir uygulama olarak kabul edilmez, bir kez daha sorgu dizelerinin adından da anlaşılacağı gibi yalnızca verileri sorgulamak için kullanılması gerektiğini söyleyen ilkeyi ihlal ediyoruz. Verileriniz üzerinde bir tür sürüm denetiminiz varsa, API’nizin ne için sorumlu olduğuna bağlı olarak sorgu dizesine bir sürüm eklemek yanlış olmaz.

Sonuç Bağlamı

Şüpheye düştüğünüzde, URI veya rota sürümü oluşturma, ilerlemenizi geliştirme sürecinizi basitleştireceği ve kullanıcılarınızı mutlu edeceği için gidilecek yoldur.

Bir tavsiye, özellikle zaten bir API’niz varsa, küçük başlamak ve kademeli olarak ilerlemek olacaktır. Bir alan seçin, API platformunuza giren ve çıkan verileri inceleyin ve standartlaştırmaya çalışın.

Her sürümü oluşturan özellikleri açıklayan ve bu veri yapısını doğrulamak için kullanılabilecek kriterleri açık bir şekilde özetleyen bir dizi şema belgesi oluşturun. Ardından, bu bilgilere kolayca erişildiğinden ve API kullanıcıları arasında paylaşıldığından emin olun.

Son olarak, OpenAPI standartları ve Schema.org gibi kaynakları okuyun . Nitelikleri belirlemenize, şemanız etrafında kuralları yapılandırmanıza ve bu bilgiyi iletmek için tek tip bir stil geliştirmenize yardımcı olabilecek bazı mükemmel yapısal kavramlar sunarlar.

Bu makaleyi okuduğunuz için teşekkürler! Bana destek olmak isterseniz;

Beni Twitter, Linkedin ve YouTube‘da takip edin.

Kısa bir yorum bırakmayı UNUTMAYIN!