REST API Sürümleme: URI, Başlık ve Geriye Uyumluluk Stratejileri

Bir API yayına alındığı anda artık yalnız sizin değildir: bayi portalı, mobil uygulama, ERP bağlayıcısı ya da iş ortağının entegrasyonu onun bugünkü davranışına bağlanır. Sahadaki tipik arıza şöyle başlar: bir alanın adı “küçük bir düzeltme” diye değiştirilir, aynı gece iş ortağının sipariş aktarımı durur ve kimse nedenini sabaha kadar bulamaz. Sürümleme, API’yi geliştirmeye devam ederken tüketicileri habersiz bozmamanın yöntemidir: kırıcı değişikliği tanımak, doğru sürümleme yöntemini seçmek ve eski sürümü takvimle kapatmak.

Sürümlemenin çözdüğü problem

API sağlayıcısı ile tüketici farklı takvimlerle çalışır. Siz bir alanın adını değiştirmek istersiniz; iş ortağınızın geliştirme ekibi aylarca o koda dokunmayabilir. Sürümleme bu iki takvimi ayırır: yeni davranış yeni sürümde yayınlanır, eski sürüm belirli bir süre aynen çalışır, tüketici geçişi kendi planına göre yapar.

Sürümleme amaç değil, son çaredir. Her yeni ana sürüm aynı anda bakımı yapılan iki kod yolu, iki belge seti ve iki test kümesi demektir. Bakım yükü ikiye katlanır. Bu yüzden ilk hedef değişiklikleri mümkün olduğunca geriye uyumlu yapmak, yeni ana sürümü yalnız kaçınılmaz olduğunda çıkarmaktır. REST ile GraphQL arasında henüz seçim aşamasındaysanız, GraphQL’in şema evrimine farklı yaklaştığını hesaba katın; bu karşılaştırma REST mi GraphQL mi rehberinde yer alıyor.

Kırıcı ve kırıcı olmayan değişiklikler

Kırıcı değişiklik, doğru yazılmış mevcut bir istemcinin hiçbir değişiklik yapılmadan çalışmayı bırakmasına yol açan değişikliktir. Aşağıdaki ayrımı değişiklik incelemesinde kontrol listesi olarak kullanın.

Değişiklik	Sınıf	Not
Yanıta yeni isteğe bağlı alan eklemek	Kırıcı değil*	İstemci bilinmeyen alanları yok saymalı
Yeni uç nokta eklemek	Kırıcı değil	—
İsteğe yeni isteğe bağlı parametre eklemek	Kırıcı değil	Varsayılan davranış değişmemeli
Alanı silmek veya yeniden adlandırmak	Kırıcı	Önce yeni alanı ekle, eskisini kaldırmayı ilan et
Alanın tipini değiştirmek (sayı → metin)	Kırıcı	Sıkı tipli istemciler ayrıştıramaz
İsteğe bağlı parametreyi zorunlu yapmak	Kırıcı	—
Enum’a yeni değer eklemek	Duruma göre	Kapalı switch yapıları kırılabilir
Doğrulama kuralını sıkılaştırmak	Kırıcı	Dün geçen istek bugün 422 alır
Varsayılan sayfa boyutunu veya sıralamayı değiştirmek	Kırıcı	Davranış değişikliği de kırıcıdır

* Yeni alan eklemenin güvenli olması, tüketicilerin “bilinmeyen alanları yok say” ilkesine uymasına bağlıdır. Bu beklentiyi API belgenize açıkça yazın; sıkı şema doğrulaması yapan istemciler yeni bir alanda bile hata verebilir. Sahada en sık bu kırılır: sağlayıcı “alan ekledik, kırıcı değil” der, tüketicinin kod üreticiyle oluşturduğu sınıf bilinmeyen alanda istisna fırlatır. Kırıcı olmayan değişikliği de sürüm notuna yazın; tüketici neyin değiştiğini görsün.

Kırıcı bir değişikliği yeni ana sürüm çıkarmadan yapmanın yaygın yolu genişlet ve daralt (expand and contract) yaklaşımıdır: yeni alan eskisinin yanına eklenir, iki alan bir süre birlikte doldurulur, eski alan kullanımdan kaldırılmış ilan edilir ve kullanım sıfıra indiğinde kaldırılır. Yavaştır. Ama kimseyi bozmaz.

URI, başlık ve parametre ile sürümleme

Yöntem	Örnek	Avantaj	Sınırlama
URI yolu	/v2/orders	Görünür, önbellek ve log dostu, yönlendirmesi kolay	Kaynağın kimliği sürümle karışır
Özel başlık	Api-Version: 2026-06-01	URI sabit kalır, tarih tabanlı ince sürümlemeye uygun	Tarayıcıda ve logda daha az görünür
Medya tipi	Accept: application/vnd.ornek.v2+json	HTTP içerik pazarlığıyla uyumlu	İstemci ve araç desteği zayıf olabilir
Sorgu parametresi	/orders?api-version=2	Basit, kolay denenir	Önbellek anahtarları ve imzalı URL’lerde karışıklık

Kurumsal web ve entegrasyon projelerinin çoğunda URI yolu ile ana sürüm pratik bir varsayılandır: iş ortağı hemen anlar, proxy, WAF ve log katmanlarında kolayca ayırt edilir. Bir olay incelemesinde erişim loguna bakıp hangi sürümün çağrıldığını tek satırda görmek ciddi zaman kazandırır. Sık ve küçük değişiklik yayınlayan sağlayıcılar ise tarih tabanlı başlık sürümlemesini tercih edebilir; örneğin GitHub REST API X-GitHub-Api-Version, Stripe ise Stripe-Version başlığıyla tarih biçiminde sürüm alır. Hangi yöntem seçilirse seçilsin üç kural değişmez:

• Sürüm belirtilmeyen isteğin davranışı belgelenmiş olmalı (en eski desteklenen sürüm veya hata). “Her zaman en yenisi” varsayılanı sürümlemenin amacını ortadan kaldırır; yeni sürüm yayınlandığı gün sürüm belirtmeyen herkes bozulur.
• Tüketiciye yalnız ana sürümler (kırıcı değişiklikler) görünür olmalı; küçük ve yama sürümleri sürüm notunda kalır.
• Webhook gövdeleri gibi sizin gönderdiğiniz olaylar da sürümlenmeli. Olay gövdesine bir şema sürümü alanı koymak, alıcının ayrıştırmayı güvenle yapmasını sağlar; alıcı tarafın tasarımı için webhook alıcısı tasarımı rehberine bakabilirsiniz.

Kullanımdan kaldırma: Deprecation ve Sunset başlıkları

Eski bir sürümü veya uç noktayı kapatma süreci tüketiciye makine tarafından okunabilir sinyallerle duyurulabilir. Sunset başlığı RFC 8594 ile tanımlıdır ve kaynağın yanıt vermeyi bırakacağı tarihi bildirir. Deprecation başlığı RFC 9745 ile standartlaşmıştır ve kaynağın kullanımdan kaldırıldığı (veya kaldırılacağı) anı yapılandırılmış bir tarih olarak taşır; tarih, @ ile başlayan Unix zaman damgası biçimindedir.

HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: @1798761600
Sunset: Thu, 01 Jul 2027 00:00:00 GMT
Link: <https://api.ornek.com/docs/v1-gecis>; rel="deprecation"

Bu örnekte @1798761600, 1 Ocak 2027 00:00 UTC anına karşılık gelir; v1 bu tarihten itibaren kullanımdan kaldırılmış sayılır ve 1 Temmuz 2027’de kapanır. Link başlığındaki deprecation ilişkisi geçiş belgesinin adresini verir. Başlıkların değeri, istemcinin bunları otomatik loglayabilmesinden gelir: başlığı gören bir HTTP istemci katmanı uyarı üretir ve geliştirici ekip durumu belge okumadan öğrenir.

Başlıklar e-posta ve portal duyurusunun yerini tutmaz, onu tamamlar. Kimse yanıt başlığını okumaz. Ama log okur. Sunset tarihinden sonra eski sürüme gelen isteklere 410 (Gone) gibi açık bir durum kodu ve geçiş belgesine işaret eden bir hata gövdesi dönün; sessiz bir 404’ün teşhisi saatler alır.

OpenAPI ile sözleşme ve değişiklik kontrolü

API sözleşmesini bir OpenAPI belgesiyle tanımlamak, kırıcı değişiklik kontrolünü insan dikkatinden çıkarıp otomasyona taşır. OpenAPI işlem, parametre ve şema düzeyinde deprecated: true işaretini destekler; belge üreticileri bu işareti görsel olarak gösterir.

paths:
  /v1/orders/{id}:
    get:
      deprecated: true
      summary: Sipariş detayı (v1, yerine /v2/orders/{id} kullanın)
components:
  schemas:
    Order:
      properties:
        customerCode:
          type: string
        customer_code:
          type: string
          deprecated: true

Sözleşme dosyası kodla aynı depoda tutulduğunda her değişiklik isteğinde önceki sürümle karşılaştırma yapılabilir. Açık kaynak oasdiff aracı iki OpenAPI belgesi arasındaki kırıcı değişiklikleri raporlar; CI hattında hata seviyesindeki bulgularda derlemeyi durduracak şekilde çalıştırılabilir:

oasdiff breaking openapi-main.yaml openapi-pr.yaml --fail-on ERR

Aracın parametreleri sürümler arasında değişebildiği için kullandığınız sürümün belgesini doğrulayın. Bu kontrol, GitHub Actions ile CI/CD hattı rehberinde anlatılan adımlarla birleştirilebilir. Bir sınırı var: otomatik karşılaştırma davranış değişikliklerini (varsayılan sıralama, doğrulama mantığı, sayfalama boyutu) yakalayamaz. Şema aynı kalır, sonuç değişir. Bunlar için sözleşme testleri ve inceleme kontrol listesi gerekir.

Entegrasyon ortaklarına geçiş süreci

Teknik mekanizmalar hazır olduğunda geçişin başarısını süreç belirler. Yeni ana sürüm çıktığında şu akışı izleyin:

1. Tüketici envanteri: Her API anahtarı veya istemci kimliğinin hangi şirkete, hangi uygulamaya ve hangi teknik sorumluya ait olduğunu kayıt altına alın. Kimin etkileneceğini bilmeden takvim ilan edilmez. Sahibi bilinmeyen anahtar, kapatma günü sürprizidir.
2. Sürüm başına kullanım ölçümü: Erişim loglarından istemci ve sürüm bazında istek sayısını raporlayın. Bu rapor geçişin ilerleyişini ve kapatma tarihinin gerçekçi olup olmadığını gösterir.
3. Duyuru ve takvim: Kullanımdan kaldırma ve kapatma tarihlerini, geçiş belgesini ve değişiklik listesini aynı anda yayınlayın. Süreyi tüketicilerin geliştirme döngüsüne ve sözleşmelerinize göre belirleyin.
4. Test ortamı: Yeni sürümü tüketicilerin deneyebileceği bir test ortamında, gerçekçi örnek veriyle erken açın.
5. Hatırlatma ve takip: Kapatma tarihi yaklaşırken hâlâ eski sürümü kullanan istemcilere doğrudan ulaşın.
6. Planlı kısa kesintiler (brownout): Bazı sağlayıcılar kapatmadan önce eski sürümü önceden duyurulmuş kısa aralıklarla devre dışı bırakır; unutulmuş entegrasyonlar kapatma gününden önce görünür olur. Bu yöntemi yalnız açık duyuruyla ve kritik iş akışlarını etkilemeyecek saatlerde uygulayın.
7. Kapatma ve temizlik: Kapatmadan sonra eski kod yolunu, belgeleri ve testleri kaldırın; aksi hâlde sürümleme borcu birikir.

Kendi geliştirdiğiniz iş uygulamaları ve iş ortağı API’leri için sürümleme ve sözleşme yönetimi kurgusunda özel web uygulaması geliştirme ve ERP, CRM ve API entegrasyonları sayfalarımızdan kapsamı inceleyebilirsiniz.

Sık sorulan sorular

API sürümlemede URI yolu mu başlık mı tercih edilmeli?

Kurumsal iş ortağı entegrasyonlarında URI yolunda ana sürüm pratik bir varsayılandır; görünürdür ve log, proxy, WAF katmanlarında kolay ayırt edilir. Sık ve küçük değişiklik yayınlayan, tarih tabanlı ince sürümleme isteyen API’lerde başlık tabanlı sürümleme daha esnektir. Hangisi seçilirse seçilsin sürümsüz isteğin davranışı belgelenmelidir.

Yanıta yeni alan eklemek kırıcı değişiklik midir?

Genel kabul gören yaklaşımda değildir; ancak bu, tüketicilerin bilinmeyen alanları yok saymasına bağlıdır. Sıkı şema doğrulaması yapan istemciler yeni bir alanda hata verebilir. Bilinmeyen alanların yok sayılması gerektiğini API belgesine açıkça yazın ve yeni alanları sürüm notlarında duyurun.

Deprecation ve Sunset başlıkları arasındaki fark nedir?

Deprecation başlığı kaynağın kullanımdan kaldırıldığı anı bildirir; kaynak çalışmaya devam eder ama yeni geliştirmede kullanılmamalıdır. Sunset başlığı kaynağın yanıt vermeyi bırakacağı tarihi bildirir. İkisi birlikte kullanıldığında tüketici hem uyarıyı hem son tarihi makine tarafından okunabilir biçimde alır.

Eski API sürümü ne kadar süre desteklenmeli?

Tek bir doğru süre yok. Süreyi tüketicilerin geliştirme döngüsü, iş ortaklarıyla yapılan sözleşmeler ve değişikliğin büyüklüğü belirler. Karar sürüm başına kullanım ölçümüne dayanmalı ve takvim, yeni sürüm yayınlanırken yazılı olarak duyurulmalıdır.