Web Api Versiyonlama
Versiyonlama yaparak web servisinizi stabil tutun
You can access the English version via this link.
Hizmet sağlayıcı — istemci (server — client) mimarisine uygun olarak uzun soluklu bir proje geliştirdiyseniz, bir noktada geriye uyumluluğu (backwards compatibility) kaybetmenize sebep olacak isteklerle karşılaşmışsınızdır. Bu gibi durumlarda var olan sistemi bozmadan geliştirme yapmanın en kolay ve pratik çözümü versiyonlama yapmaktır.
Versiyonlama aracılığıyla sistemimizde aynı anda farklı şekillerde istek alan, cevap oluşturan veya işlem yürüten hizmet uç noktalarına (endpoint) sahip olabiliriz. Yeni bir versiyon hazırladıktan sonra istemcilerin eski versiyondan yeni versiyona geçmesi için zaman tanıyabilir, belirtilen süreden sonra eski versiyonu sistemden kaldırarak son kullanıcıya hiçbir mağduriyet yaşatmadan geliştirme sürecini tamamlayabiliriz.
Not: .Net 5 ile geliştirilmiş örnek projeye GitHub üzerinden erişebilirsiniz.
Kullanıcı bilgisi, ürün kodu, ürün adedi ve adres bilgisini alarak bir sipariş kaydı oluşturuyorduğumuzu düşünelim. Şemamız aşağıdaki gibi olacaktır.
[POST] http://base-url/orders
{
"userId" : "dummy-user-id",
"productCode" : "computer-123",
"quantity" : 3,
"address" : "some dummy address"
}Sipariş sürecini hızlandırmak için adres bilgisinin sistematik bir şekilde alınması ile alakalı bir geliştirme yapılması gereksin. Artık ülke ve il bilgisinin ayrı alanlardan elde edilmesi gerekmektedir. Geliştireceğiniz yeni yapı sonucunda oluşacak isteğe ait şemanın da aşağıdaki gibi oluşacağını düşünelim.
[POST] http://base-url/orders
{
"userId" : "dummy-user-id",
"productCode" : "computer-123",
"quantity" : 3,
"country": 90,
"city" : 34,
"addressDetail" : "some dummy address detail"
}Şimdi örnek senaryomuzu göz önünde bulundurarak versiyonlamayı ne gibi şekillerde yapabileceğimize bir göz atalım.
URI ile Versiyonlama
Bu yöntemde istemciden kullanmak istediği versiyon bilgisini URI içerisinde göndermesini talep etmekteyiz.
[POST] http://base-url/v1/orders
{
"userId" : "dummy-user-id",
"productCode" : "computer-123",
"quantity" : 3,
"address" : "some dummy address"
}[POST] http://base-url/v2/orders
{
"userId" : "dummy-user-id",
"productCode" : "computer-123",
"quantity" : 3,
"country": 90,
"city" : 34,
"addressDetail" : "some dummy address detail"
}
Avantaj:
- Kullanımı kolaydır.
- Versiyonlama yapıldığına dair durum istemci tarafından kolayca farkedilebilirdir.
- Versiyonlama bilgisi URI üzerinde olduğu için istemci tarafından yapılacak cache’leme işlemi versiyon bazında yapılabilmektedir.
Dezavantaj:
- REST kurallarına uygun değildir.
- Versiyonlama değeri değiştiği zaman tüm kaynağı etkilemektedir. Bu sebeple versiyon değişikliğini tek bir hizmet noktası için yapamamış oluyoruz. Örnek vermek gerekirse biz POST hizmet uç noktası için versiyon değişikliği yapmak isterken “order” kaynağı üzerinde varsa GET, PUT, PATCH gibi işlemler için de yeni versiyonları hazırlamak zorunda kalıyoruz.
Query-Parametresi ile Versiyonlama
Bu yöntemde istemciden kullanmak istediği versiyon bilgisini query-parametresi olarak talep etmekteyiz. Bu şekilde istek objemizin şemasını biliyor olacağız.
[POST] http://base-url/orders?v=1
{
"userId" : "dummy-user-id",
"productCode" : "computer-123",
"quantity" : 3,
"address" : "some dummy address"
}
[POST] http://base-url/orders?v=2
{
"userId" : "dummy-user-id",
"productCode" : "computer-123",
"quantity" : 3,
"country": 90,
"city" : 34,
"addressDetail" : "some dummy address detail"
}
Avantaj:
- Varsayılan (default) versiyon değerinin koyulması çok daha kolaydır.
- Hizmet uç noktası bazında versiyonlama yapılabilmektedir.
Dezavantaj:
- URI üzerinden versiyonlama ile birleşirse versiyon yönetimi yapmak oldukça zor olacaktır.
- Versiyon değerinin saptanması için parametrelerin kontrol edilmesi gerekmektedir.
Header ile Versiyonlama
Bu yöntemde istemciden kullanmak istediği versiyon bilgisini istek başlığı (header) aracılığıyla göndermesini talep etmekteyiz.
x-api-version: 1
[POST] http://base-url/orders
{
"userId" : "dummy-user-id",
"productCode" : "computer-123",
"quantity" : 3,
"address" : "some dummy address"
}x-api-version: 2
[POST] http://base-url/orders
{
"userId" : "dummy-user-id",
"productCode" : "computer-123",
"quantity" : 3,
"country": 90,
"city" : 34,
"addressDetail" : "some dummy address detail"
}
Avantaj:
- Granüler bir yapı sunmaktadır. Hizmet uç noktası bazında versiyonlama yapmak oldukça kolaydır.
- Farklı versiyonlar arasında URL yapısında fark oluşmamaktadır. REST kurallarına daha uygundur.
Dezavantaj:
- URI veya Query-Parameter yöntemleri kadar görünür bir yöntem değildir.
- Tarayıcı üzerinden isteğin tekrarlanması zordur. Örneklemek gerekirse versiyon bilginizin URI veya Query-Parameter üzerinde olduğunu düşünelim. Bu senaryoda URL değerini tarayıcınıza kopyalayarak istek gönderdiğiniz zaman versiyon değeri de iletileceği için isteğinizi doğru bir şekilde iletmiş olacaksınız. Bu yöntemde (header kullanımı) ise versiyon bilgisini iletemediğiniz için isteğin işlenme şekli beklediğiniz gibi olmayabilir. İsteğinizi eksiksiz bir şekilde iletebilmek için Postman gibi istemci uygulamaları kullanmak zorunda kalacaksınız.
Web servisi versiyonlama sırasında kullanılan temel 3 yöntemden bahsetmiş oldum. Umarım yararlı bir yazı olmuştur. Diğer yazılarıma göz atmak için bu linke tıklayabilirsiniz.
