REST API Versiyonlama Teknikleri

İstemcilere sunduğunuz API sizin ile istemciler arasındaki bir sözleşme gibidir. Sözleşmeler özel ve tüzel kişileri uzun süreliğine bağlar, siz de API’daki bir özelliği sözleşmeden ötürü silemez ya da değiştiremezsiniz. Değişen ihtiyaçlara göre bir özelliği değiştirmek istediğinizde yapmanız gereken şey ise eski sözleşmeyi bozmamak ama yeni sözleşme sürümü çıkartmak, yani versiyonlamak.

https://xkcd.com/1172/

API versiyonlaması yaparken kullanabileceğiniz 7 farklı tekniği inceleyelim:

1. Media Type Versiyonlama Tekniği

“Content Negotiation” ya da “Accept Header” olarak da bilinir. Accept Header bilgisinin özelliştirilmiş bir media type şeklinde sunulması şeklindedir. 
Örnek : Accept: application/vnd.myapi.v2+json ya da Accept: Application/vnd.api.article+xml; version=1.0

Avantajları

Dezavantajları

  • Sadece browser kullanarak API’yı görüntülemeniz mümkün değildir. Devtools gibi araçlara ihtiyaç duymanız gereklidir.
  • HTTP headerlarını amacı dışında kullanmaya yol açar.
  • İstemciler her kaynağın özel media type’ını bilmek zorundadırlar.

Referanslar

2. Header Versiyonlama Tekniği

Versiyonun özel bir header ile belirtilmesi şeklindedir.
Örnek: Version: 1.0 ya da API-Version: 1.0

Avantajları

  • URI de versiyon belirtilmediği için farklı versiyonlarda dahi aynı URI yapısını korur.
  • İlerde bahsedeceğimiz URI değiştirilen tekniklere göre çok daha temiz bir çözüm sunar.

Dezavantajları

  • Kaynakları versiyonlamak için bu tekniği kullanıyorsanız, API versiyonunu yönetmek karışık hale gelebilir.

Referanslar

3. URI Versiyonlama Tekniği

Bu teknik ile her versiyon için API endpointlerinizi farklı bir dizinde sunabilirsiniz . 
Örnek: api.example.com/v1/resource

Avantajları

  • Kullanması kolaydır
  • Günümüzde en çok tercih edilen yöntemdir.
  • Farklı versiyonlar tarayıcı üzerinden keşfedilebilir durumdadır.

Dezavantajları

  • RESTful uyumlu değildir. URI’ler versiyon için değil sadece kaynakları görüntülemek için kullanılmadır.
  • Tüm API yerine kaynakları ayrıca versiyonlamak için kullanılması gerektiğinde mümkün olduğunca uzak durmaya çalışılmalıdır.

Referanslar

4. Domain Versiyonlama Tekniği

URI tekniğinin farklı domainlerde sunulması şeklindedir. URI tekniğinin avantaj ve dezavantajlarını barındırır. 
Örnek: apiv1.example.com/resource

Avantajları

  • Versiyonları farklı sunucularda rahatlıkla barındırmanızı sağlar.
  • Aynı kaynakları kullanan çok farklı bir API geliştirken yardımcı olacaktır.

Dezavantajları

  • URI tekniğinin dezavantajlarının yanısıra istemciler güvenlik ayarlarını (firewall vs.) değiştirmek zorunda kalacaklardır.

5. Parametre Versiyonlama Tekniği

Yapılan sorgunun içinde parametre olarak versiyonun belirtilmesi şeklindedir. 
Örnek: GET /resource?version=1.0

Avantajları

  • Javascript ile kullanımı kolaydır. aynı sunucuda CORS ayarı yapmaya gerek kalmaz.
  • URI tekniğinde olduğu gibi browserdan rahatça görüntülenebilmeyi sağlar.
  • Opsiyonel olabilir. Parametre belirtilmediği takdirde son versiyon sunulur.

Dezavantajları

  • Kaynakları ayrı ayrı ve API nin tamamını aynı anda versiyonlamak istediğinizde işler çığrından çıkabilir.

6. Tarih Bazlı Versiyonlama Tekniği

Versiyonlar 2016–01–04 şeklindedir. API istemcisi ilk sorgusunu yaptığı andaki en son versiyon kaydedilir. API istemcisi manuel olarak versiyonunu değiştirmediği sürece bu kullanılır.

Avantajları

  • Yeni API özelliklerini URI de değişiklik yapmadan sunmayı sağlar.
  • Hangi istemcinin hangi versiyonu kullandığını tespit etmeyi kolaylaştırır.

Dezavantajları

  • Uygulamaya geçirmesi zordur.

Referanslar

Genel Hatırlatmalar

  • Response header içerisinde istemcinin hangi versiyonu kullandığı belirtin. Hele ki versiyon belirtmenin opsiyonel olduğu durumlarda.
  • Her versiyon için farklı dökümantasyon sayfasını erişilebilir durumda tutun.
  • Eski versiyonların ne kadar süre ile çalışmaya devam edeceğini açık bir şekilde duyurun.
  • API’daki yeniliklerden istemcilerinizi e-posta vb. yollar ile bilgilendirmeyi unutmayın.

Okumalar