REST API Versiyonlama Stratejileri ve İstemci Yönetimi

Bir REST API ilk yayına çıktığında versiyonlama çoğu ekip için uzak bir konu gibi görünür. Asıl sınav, ilk gerçek istemciler sisteme bağlandıktan ve API artık başka uygulamaların günlük iş akışının parçası olduktan sonra başlar. REST API Versiyonlama Stratejileri ve İstemci Yönetimi, yalnızca URL'ye v1 veya v2 eklemek değildir; sözleşmeyi, istemcileri, SDK'ları, dokümantasyonu, migration takvimini ve eski sürümlerin kapatılma sürecini birlikte yönetmeyi gerektirir. On yılı aşan backend ve entegrasyon çalışmaları içinde gördüğüm en önemli nokta, iyi tasarlanmış bir API'nin değişiklikten kaçınan değil, değişikliği kontrollü biçimde taşıyabilen API olduğudur. Bu rehberde REST API versiyonlama nasıl yapılır, REST API versioning stratejileri nelerdir, URL header ve query parameter API versiyonlama yöntemleri karşılaştırması nasıl değerlendirilir ve API versiyon değişikliklerinde backward compatibility deprecation ve istemci migration yönetimi nasıl planlanır sorularını pratik örneklerle ele alacağız.

REST API Versiyonlama Nedir?

REST API versiyonlama, bir API sözleşmesinin zaman içinde değişmesine rağmen mevcut istemcilerin çalışmaya devam etmesini sağlayan yönetim yaklaşımıdır. Buradaki amaç her değişiklikte yeni bir sürüm çıkarmak değil, hangi değişikliğin hangi istemciyi etkileyebileceğini önceden anlamaktır. Sağlam bir versiyonlama yaklaşımı API'nin teknik arayüzü kadar ürün yaşam döngüsünü de kapsar. Sürüm numarası ancak arkasında açık support window, migration planı ve uyumluluk politikası varsa anlam kazanır. Bu nedenle versiyonlama kararını routing ayrıntısı olarak değil, API contract yönetiminin bir parçası olarak düşünmek daha doğru olur.

API Sözleşmesi Nedir?

API sözleşmesi, istemcinin sunucudan hangi isteği kabul etmesini ve hangi cevabı üretmesini bekleyebileceğini tanımlar. Endpoint adresleri, alan adları, veri tipleri, status code'lar, authentication gereksinimleri ve hata yapıları bu sözleşmenin görünen parçalarıdır. Fakat gerçek sistemlerde istemciler çoğu zaman dokümantasyonda yazmayan davranışlara da bağımlı hale gelir. Örneğin kayıtların sürekli aynı sırada dönmesi belgelenmemiş olsa bile bazı istemciler bu sırayı varsayabilir. Bu nedenle sözleşme değerlendirilirken yalnızca OpenAPI dosyasına değil, production kullanımına da bakmak gerekir.

API'ler Neden Zaman İçinde Değişir?

API'ler ürün ihtiyaçları, güvenlik gereksinimleri, veri modeli değişiklikleri, performans çalışmaları ve yeni entegrasyonlar nedeniyle zaman içinde değişir. İlk tasarımın yıllar boyunca hiç değişmeyeceğini düşünmek gerçekçi değildir. Yeni bir müşteri türü farklı alanlara ihtiyaç duyabilir, eski bir endpoint operasyonel yük oluşturabilir veya authentication modeli güçlendirilmek zorunda kalabilir. İyi API tasarımı değişimi engellemeye çalışmak yerine değişikliğin etkisini yönetilebilir hale getirir. Bu yaklaşım ekiplerin yeni özellik yayınlamasını kolaylaştırırken mevcut istemcilerin beklenmedik biçimde bozulma riskini azaltır.

Versioning ile API Evolution Arasındaki Fark

Versioning belirli bir API sözleşmesini ayrı bir sürüm kimliği altında sunmayı ifade ederken API evolution aynı sözleşmenin uyumlu biçimde geliştirilmesini kapsar. Her evolution adımı yeni bir sürüm gerektirmez. Örneğin istemcilerin güvenle görmezden gelebileceği opsiyonel bir response alanı eklemek mevcut sürüm içinde yapılabilir. Buna karşılık bir alanın veri tipini değiştirmek açık bir uyumluluk riski oluşturduğu için yeni sürüm gerektirebilir. Ekiplerin bu ayrımı doğru kurması version proliferation sorununu azaltır ve API yaşam döngüsünü daha anlaşılır hale getirir.

API Versiyonlamasının Temel Hedefleri

API versiyonlamasının temel hedefi, ürün geliştirme hızı ile istemci istikrarı arasında sürdürülebilir bir denge kurmaktır. Yeni özellikler yayınlanabilmeli, fakat yıllardır çalışan entegrasyonlar habersiz şekilde bozulmamalıdır. Eski davranışlar sonsuza kadar tutulmamalı, ancak kaldırma işlemi ölçülebilir ve öngörülebilir bir süreçle yapılmalıdır. Migration maliyetinin yalnızca backend ekibine değil, istemci sahiplerine de yayıldığı unutulmamalıdır. Başarılı bir politika bu hedefleri teknik kurallar, iletişim kanalları ve gözlemlenebilir kullanım verileriyle destekler.

Mevcut istemcileri bozmamak

Mevcut istemcileri bozmamak, versiyonlamanın en temel beklentisidir. Bir istemci bugün çalışan isteğinin yarın aynı sözleşme altında anlamsız şekilde değişmeyeceğini bilmek ister. Bunun için breaking change tanımı ekip içinde açıkça yazılmalı ve release süreçlerine eklenmelidir. Production trafiğinde hangi istemcinin hangi davranışa bağımlı olduğunu izlemek de karar kalitesini yükseltir. Böylece API ekibi yalnızca teorik uyumluluğu değil, gerçek kullanıcı etkisini de değerlendirebilir.

Yeni özellikleri yayınlayabilmek

Uyumluluk politikası yeni özellik geliştirmeyi engellememelidir. İyi tasarlanmış bir API, opsiyonel alanlar, yeni endpoint'ler ve capability mekanizmaları sayesinde mevcut istemcileri bozmadan gelişebilir. Burada önemli olan değişikliklerin additive görünmesine aldanmamaktır. Yeni alanların strict parser kullanan istemciler üzerindeki etkisi test edilmelidir. Böylece ürün ekibi yenilik yayınlarken entegrasyon ekipleri de daha öngörülebilir bir sözleşmeyle çalışabilir.

Eski davranışları kontrollü kaldırmak

Eski davranışları sonsuza kadar desteklemek teknik borcu ve operasyonel maliyeti artırır. Bu nedenle her API sürümünün tanımlı bir yaşam döngüsü bulunmalıdır. Deprecation duyurusu, migration rehberi, kullanım ölçümü ve sunset tarihi aynı planın parçaları olmalıdır. İstemcilerin yeni sürüme geçiş durumu takip edilmeden route kaldırmak gereksiz kesintilere yol açabilir. Kontrollü kaldırma yaklaşımı hem geliştirme ekibine hem de API tüketicilerine planlama alanı sağlar.

Migration maliyetini yönetmek

Migration maliyeti yalnızca birkaç endpoint'i değiştirmekten ibaret değildir. SDK güncellemesi, test, release, uygulama mağazası onayı, müşteri koordinasyonu ve operasyonel takip bu maliyetin parçaları olabilir. Bu nedenle migration süresi her istemci türü için aynı kabul edilmemelidir. Büyük kurumsal entegrasyonların değişiklik takvimi ile kontrol edilen bir web istemcisinin takvimi farklıdır. Maliyet görünür hale getirildiğinde sürüm politikaları daha gerçekçi oluşturulabilir.

API'nin Gerçek Sözleşmesi Nelerden Oluşur?

Bir API'nin gerçek sözleşmesi yalnızca URL ve JSON şemasından oluşmaz. İstemci davranışını etkileyen status code, authentication yöntemi, hata formatı, rate limit ve SDK davranışı da sözleşmenin parçasıdır. Ayrıca belgelenmemiş fakat production istemcilerinin dayandığı davranışlar da pratikte sözleşmeye dönüşebilir. Bu nedenle breaking change analizi yalnızca schema diff ile sınırlandırılmamalıdır. En güvenli yaklaşım, API'yi istemcinin gözünden değerlendirmek ve gözlemlenebilir davranışların tamamını contract kapsamına almaktır.

HTTP Endpoint

HTTP endpoint, istemcinin kaynak veya işleme ulaştığı temel giriş noktasıdır. Bir endpoint'in kaldırılması, yolunun değiştirilmesi veya HTTP metodunun farklılaştırılması doğrudan istemci kodunu etkileyebilir. Route yapısı açık olduğunda gateway, cache ve dokümantasyon süreçleri de daha rahat yönetilir. Endpoint tasarımında gereksiz sürüm parçalanmasından kaçınmak uzun vadeli bakım maliyetini azaltır. Özellikle public API'lerde adres kararlılığı önemli bir güven unsuru oluşturur.

Request Schema

Request schema, istemcinin hangi alanları hangi veri tipleriyle gönderebileceğini tanımlar. Optional bir alanın required yapılması çoğu durumda mevcut istemciler için breaking change oluşturur. Yeni validation kuralları da schema görünümü değişmese bile istemci davranışını bozabilir. Bu nedenle request tarafındaki değişiklikler hem yapısal hem davranışsal olarak değerlendirilmelidir. Contract testleri gerçek istemci örneklerinin yeni server sürümünde kabul edilip edilmediğini görmek için oldukça değerlidir.

Response Schema

Response schema, istemcinin cevabı nasıl parse edeceğini belirleyen önemli bir sözleşme parçasıdır. Alan kaldırmak veya veri tipini değiştirmek açık bir kırılma oluşturabilir. Yeni alan eklemek çoğu zaman güvenli kabul edilse de strict deserialization yapan istemciler bunu reddedebilir. Bu nedenle response evolution yaklaşımı istemcilerin unknown field toleransını dikkate almalıdır. SDK üretimi sırasında kullanılan modeller de bu değişikliklerin etkisini büyütebilir veya azaltabilir.

HTTP Status Codes

HTTP status code'lar yalnızca teknik ayrıntı değildir, istemci kontrol akışının doğrudan parçasıdır. Bir istemci 404 gördüğünde farklı, 403 gördüğünde farklı aksiyon alabilir. Aynı başarılı operasyonu 200 yerine 204 ile döndürmek bile body bekleyen istemcileri etkileyebilir. Retry politikaları da çoğu zaman status code sınıflarına göre çalışır. Bu nedenle status code değişiklikleri contract review sürecine dahil edilmelidir.

Error Schema

Hata şeması, istemcilerin sorunları makine tarafından yorumlayabilmesini sağlar. Sadece insan tarafından okunacak bir message alanına güvenmek uzun vadede zayıf bir entegrasyon deneyimi oluşturur. Sabit error code, error type ve field-level validation ayrıntıları istemci davranışını daha öngörülebilir yapar. Bu alanların isimlerini veya anlamlarını değiştirmek normal response değişiklikleri kadar önemli olabilir. SDK exception mapping de doğrudan bu sözleşmeye bağlı olduğundan versioning politikasında error schema açıkça ele alınmalıdır.

Authentication

Authentication yöntemi API sözleşmesinin güvenlik açısından en kritik parçalarından biridir. API key'den OAuth tabanlı bir yapıya geçmek istemci kodu, credential yönetimi ve operasyonel süreçlerde değişiklik oluşturur. Böyle bir geçiş çoğu zaman paralel authentication dönemi gerektirir. Credential rotation ve yeni token formatlarının desteklenmesi migration takvimine dahil edilmelidir. Authentication değişikliği güvenlik amacı taşısa bile istemci etkisi ayrı olarak yönetilmelidir.

Rate Limits

Rate limit değerleri istemcinin trafik planlamasını ve retry davranışını doğrudan etkileyebilir. Bir quota'nın düşürülmesi sözleşme dosyasında görünmese bile mevcut iş akışını bozabilir. İstemcilerin 429 yanıtlarını ve Retry-After bilgisini doğru yorumlayabilmesi önemlidir. SDK tarafında otomatik retry varsa yeni limitlerin bu davranışla birlikte değerlendirilmesi gerekir. Rate limit politikasının sürüm bazında izlenmesi özellikle büyük istemci portföylerinde yararlıdır.

OpenAPI Specification

OpenAPI Specification, API sözleşmesini makine tarafından okunabilir hale getirmenin güçlü yollarından biridir. Endpoint, parameter, schema, response ve security tanımları tek bir contract kaynağında tutulabilir. Bu dosya SDK generation, lint, diff ve dokümantasyon süreçlerinin temelini oluşturabilir. Fakat spec güncel değilse otomasyon yanlış güven duygusu yaratır. Bu nedenle server davranışı ile OpenAPI arasında sürekli senkronizasyon ve CI/CD kontrolü kurulmalıdır.

SDK Davranışı

SDK, ham HTTP sözleşmesini geliştiricinin kullandığı metodlara ve modellere dönüştürür. Bu dönüşüm sırasında nullable alanlar, enum değerleri, exception türleri ve default değerler farklı davranışlara yol açabilir. API geriye uyumlu olsa bile SDK major değişikliği istemci kodunu kırabilir. Bu nedenle API version ile SDK version birbirinden ayrı düşünülmelidir. Compatibility matrix, hangi SDK sürümünün hangi API contract sürümüyle çalıştığını açık biçimde göstermelidir.

Dokümante Edilmemiş Ama İstemcilerin Bağımlı Olduğu Davranışlar

Gerçek production sistemlerinde istemciler bazen resmi sözleşmede bulunmayan davranışlara bağımlı hale gelir. Liste sırası, boş alanların null yerine hiç dönmemesi veya belirli hata mesajlarının metni buna örnek olabilir. Bu davranışlar değiştirilince API teorik olarak aynı görünse bile istemciler bozulabilir. Trafik replay ve golden client testleri bu tür gizli bağımlılıkları yakalamaya yardımcı olur. API ekibi mümkün olduğunca davranışları açık contract haline getirmeli ve belirsiz beklentileri azaltmalıdır.

Ne Zaman Yeni API Sürümü Çıkarmak Gerekir?

Yeni API sürümü çıkarmak, genellikle mevcut sözleşmenin geriye uyumlu biçimde korunamadığı durumlarda anlamlıdır. Her özellik eklemesi veya bug fix yeni sürüm gerektirmez. Karar verirken yapısal breaking change kadar davranış değişiklikleri, güvenlik gereksinimleri ve gerçek istemci kullanımı değerlendirilmelidir. Yeni sürüm açmanın uzun süreli support, dokümantasyon, SDK ve monitoring maliyeti oluşturacağı unutulmamalıdır. Bu nedenle versioning kararı teknik bir refleks değil, yaşam döngüsü maliyetini de içeren bilinçli bir karar olmalıdır.

Breaking Change

Breaking change, desteklenen bir istemcinin daha önce çalışan entegrasyonunu değiştirmeden kullanmaya devam edememesine neden olan değişikliktir. Alan kaldırmak, tip değiştirmek veya yeni required parameter eklemek açık örneklerdir. Bunun yanında authorization veya sıralama davranışındaki değişiklikler de kırılma yaratabilir. Breaking change yeni bir API sürümü, compatibility adapter veya kontrollü migration gerektirebilir. Kararın production kullanım verileriyle desteklenmesi riskin daha doğru ölçülmesini sağlar.

Non-Breaking Change

Non-breaking change, mevcut istemcilerin aynı sözleşmeyle çalışmaya devam edebildiği değişikliktir. Yeni endpoint eklemek veya gerçekten opsiyonel bir request alanı sunmak buna örnek olabilir. Ancak değişikliğin kağıt üzerinde additive olması tek başına yeterli değildir. Strict parser, generated SDK veya enum davranışı gibi ayrıntılar istemci tarafında beklenmeyen etki yaratabilir. Bu nedenle non-breaking sınıflandırması test ve compatibility analiziyle doğrulanmalıdır.

Behavioral Breaking Change

Behavioral breaking change, schema aynı görünürken API davranışının istemci sonucunu değiştirmesidir. Default sıralamanın değişmesi, daha sert authorization uygulanması veya farklı error code dönmesi bu sınıfa girebilir. Structural diff araçları bu değişiklikleri her zaman yakalayamaz. Production testleri, business rule testleri ve consumer contract'ları bu nedenle önemlidir. API versioning politikasında davranışsal kırılmaların da açık bir tanımı bulunmalıdır.

Contract Değişmeden Davranışın Değişmesi

OpenAPI dosyası aynı kalırken server davranışı değişebilir ve istemciler yine etkilenebilir. Örneğin aynı endpoint aynı schema ile cevap verirken filtre mantığı değişebilir. Benzer şekilde pagination sırası veya timeout davranışı farklılaşabilir. Bu tür değişiklikler yalnızca schema karşılaştırmasına güvenen ekiplerde kolayca gözden kaçabilir. Gerçek istemci senaryolarının test edilmesi ve davranış değişikliklerinin release notlarına eklenmesi önemli bir koruma sağlar.

Güvenlik Nedeniyle Zorunlu Breaking Change

Bazen güvenlik açığını kapatmak için geriye uyumluluğu korumak mümkün olmayabilir. Zayıf authentication yöntemi, riskli token formatı veya yanlış authorization davranışı hızla değiştirilmek zorunda kalabilir. Böyle durumlarda normal migration süresi kısalabilir, fakat istemci iletişimi yine ihmal edilmemelidir. Mümkünse geçici compatibility mekanizması veya kontrollü grace period değerlendirilmelidir. Güvenlik istisnalarının normal versioning policy içinde önceden tanımlanması kriz anında karar süresini kısaltır.

Breaking Change Nedir?

Breaking change kavramını ekip içinde net tanımlamak API yönetişiminin en önemli adımlarından biridir. Yalnızca endpoint kaldırmak değil, istemcinin varsayımlarını geçersiz kılan birçok değişiklik breaking olabilir. Request ve response alanları, status code'lar, authentication, authorization ve validation davranışı birlikte değerlendirilmelidir. Bir değişikliğin kırıcı olup olmadığını belirlerken supported client'ların nasıl çalıştığına bakmak gerekir. Bu yaklaşım, teorik contract ile production gerçekliği arasındaki farkı azaltır.

Endpoint Kaldırmak

Kullanılan bir endpoint'i kaldırmak en açık breaking change örneklerinden biridir. İstemci eski route'a istek göndermeye devam ettiğinde 404 veya başka bir hata ile karşılaşır. Yeni endpoint hazır olsa bile istemcinin otomatik olarak onu kullanması beklenemez. Removal öncesinde deprecation, migration rehberi ve kullanım ölçümü bulunmalıdır. Kapatma sonrasında da yapılandırılmış hata ve replacement bilgisi sunmak geçişi kolaylaştırır.

Endpoint Adını Değiştirmek

Endpoint yolunu değiştirmek istemci kodundaki URL bağımlılığını doğrudan etkiler. Yeni isim daha tutarlı görünse bile eski route'u aniden kaldırmak gereksiz kırılma oluşturabilir. Bir süre redirect veya adapter kullanmak bazı senaryolarda uygun olabilir, fakat HTTP method ve body semantiği dikkatle korunmalıdır. Daha güvenli yaklaşım eski endpoint'i deprecated olarak tutup yenisini paralel sunmaktır. Kullanım sıfıra yaklaştığında eski route kontrollü biçimde kapatılabilir.

Request Field Kaldırmak

Request alanı kaldırmak, alanı göndermeye devam eden istemciler için risk oluşturur. Server unknown field kabul ediyorsa istek çalışabilir, fakat strict validation varsa hata üretilebilir. Alan artık kullanılmıyorsa önce ignored veya deprecated hale getirmek migration sürecini kolaylaştırır. SDK modellerinde alanın kaldırılması ayrıca compile-time değişiklik yaratabilir. Bu nedenle server contract ile SDK yaşam döngüsü birlikte planlanmalıdır.

Response Field Kaldırmak

Response alanı kaldırmak, o değeri okuyan istemcilerin doğrudan bozulmasına neden olabilir. Alan opsiyonel görünse bile istemci kodu gerçekte onu required kabul etmiş olabilir. Önce kullanım analizi yapmak veya yeni alana paralel geçiş sunmak daha güvenlidir. SDK tarafında property kaldırılması ayrıca major package release gerektirebilir. Removal tarihi istemcilere açık şekilde duyurulmalı ve migration örnekleri sağlanmalıdır.

Field Adını Değiştirmek

Field adını değiştirmek çoğu istemci için eski alanı kaldırıp yeni alan eklemekle aynı etkiye sahiptir. Daha okunabilir bir isim seçmek tek başına kırılmayı haklı çıkarmaz. Geçiş döneminde eski ve yeni alan birlikte döndürülebilir veya adapter kullanılabilir. İstemciler yeni alanı kullanmaya başladıktan sonra eski alan deprecated hale getirilebilir. Bu yöntem migration sürecini daha kontrollü ve ölçülebilir yapar.

Veri Tipini Değiştirmek

Bir alanı integer'dan string'e çevirmek gibi veri tipi değişiklikleri deserialization süreçlerini doğrudan etkiler. Dynamic dillerde bazı istemciler bunu tolere etse bile typed SDK'lar genellikle hata verir. Yeni tip gerekiyorsa yeni alan eklemek veya yeni API version kullanmak daha güvenli olabilir. Migration rehberinde dönüşüm örnekleri açıkça gösterilmelidir. Production traffic replay de gerçek payload'ların yeni tipe uyumunu doğrulamak için kullanılabilir.

Optional Alanı Required Yapmak

Optional alanı required hale getirmek, eski istemcilerin göndermediği bir değeri artık zorunlu kılar. Bu nedenle request tarafında açık bir breaking change olarak değerlendirilmelidir. Önce alan optional eklenip kullanım oranı artırılabilir ve SDK'larda uyarı verilebilir. Daha sonra yeni sürümde required hale getirmek daha güvenli bir geçiş sağlar. Validation hatalarının da migration dokümantasyonunda örneklenmesi geliştirici deneyimini iyileştirir.

Yeni Required Parameter Eklemek

Yeni required parameter eklemek mevcut istemcilerin eski request yapısıyla çağrı yapmasını engeller. Parametre iş gereği zorunlu olsa bile eski sözleşme açısından breaking change oluşur. Geçiş için server tarafında geçici default değer kullanılabilir veya yeni version açılabilir. İstemcilerin parametreyi göndermeye başladığı telemetri üzerinden izlenebilir. Zorunluluk ancak desteklenen istemcilerin hazır olduğu kanıtlandıktan sonra uygulanmalıdır.

Authentication Gereksinimini Değiştirmek

Authentication gereksinimi değiştiğinde istemcilerin credential edinme ve gönderme biçimi de değişir. API key'den token tabanlı yönteme geçiş buna tipik bir örnektir. İki yöntemin belirli süre paralel çalışması migration riskini azaltabilir. Yeni credential oluşturma, rotation ve iptal süreçleri açıkça belgelenmelidir. Eski yöntemin sunset tarihi istemci bazında kullanım ölçümüyle desteklenmelidir.

Authorization Davranışını Değiştirmek

Authorization değişikliği endpoint aynı olsa bile daha önce erişilebilen verinin artık erişilememesine yol açabilir. Güvenlik açısından doğru bir düzeltme olsa bile istemci iş akışını etkileyebilir. Yeni scope veya role gereksinimleri önceden duyurulmalı ve test ortamında doğrulanabilmelidir. Error response yapısı da istemcinin problemi doğru tanımasını sağlamalıdır. Böylece güvenlik iyileştirmesi yapılırken entegrasyon kesintisi azaltılabilir.

Non-Breaking Değişiklikler Nelerdir?

Non-breaking değişiklikler mevcut istemcilerin aynı entegrasyon koduyla çalışmaya devam edebildiği geliştirmelerdir. Yeni endpoint, opsiyonel parameter veya yeni opsiyonel özellik genellikle bu gruptadır. Ancak generated SDK, strict validator ve enum handling gibi ayrıntılar nedeniyle teorik olarak güvenli görünen değişiklikler pratikte sorun çıkarabilir. Bu nedenle additive change politikası istemci tolerans kurallarıyla birlikte tanımlanmalıdır. Gerçek güven, yalnızca değişikliğin türünden değil, compatibility testlerinden gelir.

Yeni Endpoint Eklemek

Yeni endpoint eklemek mevcut route'ların davranışını değiştirmediği sürece genellikle güvenlidir. Eski istemciler bu endpoint'i bilmediği için mevcut akışlarına devam eder. Yeni istemciler ise özelliği kademeli biçimde kullanmaya başlayabilir. Dokümantasyon ve SDK generation sürecinin yeni endpoint'i doğru göstermesi gerekir. Böyle bir additive evolution yeni major API version gerektirmeden ürünün gelişmesini sağlar.

Optional Request Parameter Eklemek

Opsiyonel request parameter mevcut istemcilerin göndermesi gerekmeyen yeni bir kontrol sunar. Parameter gerçekten optional olmalı ve gönderilmediğinde eski davranış korunmalıdır. Default değerin sessizce mevcut sonucu değiştirmemesi önemlidir. SDK generation sırasında parameter'ın zorunlu hale gelmediği test edilmelidir. Bu koşullar sağlandığında aynı API version içinde güvenle yayınlanabilir.

Yeni Response Field Eklemek

Yeni response alanı çoğu esnek JSON istemcisi için additive bir değişikliktir. Ancak unknown field reddeden deserializer'lar bu durumda hata verebilir. Bu nedenle API tasarımında istemcilerin bilinmeyen alanları görmezden gelmesi teşvik edilmelidir. SDK modelleri de forward compatibility göz önünde bulundurularak üretilmelidir. Böylece response schema zaman içinde yeni bilgilerle genişletilebilir.

Yeni Response Header Eklemek

Yeni response header eklemek mevcut istemciler tarafından genellikle görmezden gelinir. Bu özellik deprecation, rate limit veya tracing gibi ek bilgiler taşımak için kullanışlıdır. İstemci yalnızca bildiği header'lara göre davranıyorsa mevcut akış etkilenmez. Yine de proxy ve cache katmanlarının header davranışı test edilmelidir. Özellikle caching semantics ile ilişkili header'lar yayın öncesinde gateway ortamında doğrulanmalıdır.

Validation Kurallarını Gevşetmek

Validation kurallarını gevşetmek daha önce reddedilen bazı değerlerin kabul edilmesini sağlayabilir. Mevcut geçerli request'ler çalışmaya devam ettiği için bu değişiklik çoğu durumda non-breaking kabul edilir. Fakat yeni kabul edilen değerlerin downstream sistemlerde farklı davranış oluşturmadığından emin olunmalıdır. Business rule değişikliği varsa yalnızca schema açısından değerlendirme yapmak yeterli olmaz. Contract ve integration testleri yeni kabul aralığını doğrulamalıdır.

Yeni Opsiyonel Özellik Eklemek

Opsiyonel özellik, istemci açıkça talep etmediği sürece eski davranışı koruyorsa güvenli evolution sağlar. Feature parameter, capability veya yeni endpoint üzerinden sunulabilir. Özelliğin default olarak etkinleşmesi mevcut istemcileri etkileyebileceği için dikkatle değerlendirilmelidir. Yeni davranışın telemetry ile izlenmesi rollout sırasında fayda sağlar. Böylece özellik ile contract değişikliği birbirinden daha temiz ayrılabilir.

"Additive Change" Her Zaman Güvenli midir?

Additive change kavramı API tasarımında sık kullanılır, fakat her ekleme otomatik olarak güvenli değildir. Özellikle generated SDK kullanan veya strict JSON validation uygulayan istemciler yeni alan ve enum değerlerinden etkilenebilir. Bir response'a yeni field eklenmesi teorik olarak uyumlu görünürken deserializer bunu beklenmeyen veri kabul edebilir. Aynı şekilde yeni enum değeri exhaustive switch kullanan kodda beklenmeyen branch oluşturabilir. Bu nedenle additive değişiklikler de gerçek client davranışına göre test edilmelidir.

Strict JSON Validation

Strict JSON validation, istemcinin yalnızca tanımlı alanları kabul etmesini sağlar. Bu yaklaşım bazı hata türlerini erken yakalasa da API evolution açısından kırılganlık yaratabilir. Server yeni bir response field eklediğinde istemci bilinmeyen alan nedeniyle tüm cevabı reddedebilir. Public API'lerde mümkün olduğunca forward-compatible parsing yaklaşımı tercih edilmelidir. SDK üretim kuralları da unknown field davranışını açıkça test etmelidir.

Unknown Field Rejection

Unknown field rejection istemcinin şemada bulunmayan alanı hata olarak değerlendirmesidir. Bu davranış response tarafında additive evolution imkanını ciddi biçimde sınırlar. API sağlayıcısı her yeni alan için sürüm açmak zorunda kalabilir. Daha esnek istemci yaklaşımı bilinen alanları işlerken bilinmeyenleri güvenle yok saymaktır. Güvenlik açısından doğrulama gereken request ve tolerans beklenen response davranışları ayrı değerlendirilebilir.

Yeni Enum Value Problemi

Yeni enum değeri eklemek sıkça gözden kaçan compatibility risklerinden biridir. İstemci yalnızca bilinen üç değerin geleceğini varsaymışsa dördüncü değer çalışma zamanında sorun yaratabilir. Generated SDK enum'u kapalı tip olarak üretmişse deserialization hatası da oluşabilir. Unknown veya fallback seçeneği bulunan enum tasarımları bu riski azaltır. Yeni enum değerleri release ve compatibility testlerinde ayrı bir kural olarak değerlendirilmelidir.

Exhaustive Switch/Match

Exhaustive switch veya match yapıları bilinen tüm enum değerlerinin ayrı branch ile ele alınmasını sağlar. Yeni enum değeri geldiğinde bazı diller compile-time, bazıları runtime problemi oluşturabilir. API tarafı additive değişiklik yaptığını düşünürken istemci kodu beklenmedik duruma düşebilir. Default branch veya unknown temsilinin kullanılması forward compatibility sağlar. SDK dokümantasyonu da geliştiricilere bu kullanım biçimini açıkça önermelidir.

SDK Deserialization

SDK deserialization katmanı API cevabını uygulama modeline dönüştürdüğü için compatibility açısından kritik bir noktadır. Yeni alan, yeni enum veya nullable değişikliği burada hata üretirse ham HTTP sözleşmesinin uyumlu olması yeterli olmaz. Generated SDK ayarları üretimden önce compatibility testine tabi tutulmalıdır. Eski SDK ile yeni server kombinasyonu özellikle test edilmelidir. Böylece API evolution'ın istemci paketleri üzerindeki gerçek etkisi görülür.

Response Sırasına Bağımlı İstemciler

Bir API response listesinin sırası dokümante edilmemiş olsa bile istemciler buna güvenebilir. Backend sorgusu değiştiğinde aynı kayıtlar farklı sırada dönerek kullanıcı deneyimini veya iş mantığını etkileyebilir. Sıralama önemliyse contract içinde açık biçimde tanımlanmalıdır. Gerektiğinde sort parametresi sunmak davranışı istemci tarafından kontrol edilebilir hale getirir. Belirsiz default sıralamaya bağımlı entegrasyonlar production replay sırasında ayrıca incelenmelidir.

Hyrum's Law

Hyrum's Law, yeterince çok API tüketicisi olduğunda gözlemlenebilir her davranışın birileri tarafından kullanılabileceğini hatırlatan güçlü bir düşünce modelidir. Bu fikir API sözleşmesinin dokümantasyondan daha geniş olabileceğini anlamaya yardımcı olur. Response sırası, zamanlama veya hata biçimi istemciler için fiili bağımlılığa dönüşebilir. Bu nedenle geniş public API'lerde değişiklik etkisi yalnızca tasarım niyetine göre değerlendirilmemelidir. Telemetri, consumer inventory ve gerçek kullanım testleri karar sürecinin parçası olmalıdır.

Forward-Compatible API Nasıl Tasarlanır?

Forward-compatible API, server zaman içinde gelişirken eski istemcilerin yeni cevapları mümkün olduğunca güvenle işleyebilmesini sağlar. Bunun için optional field, unknown field toleransı, extensible object ve fallback enum gibi tasarım kalıpları kullanılabilir. Amaç her geleceği önceden tahmin etmek değil, sözleşmeye genişleyebilecek alanlar bırakmaktır. İstemcilerin gereksiz varsayımlar yapmasını önleyen dokümantasyon da teknik tasarım kadar önemlidir. Bu yaklaşım yeni major sürüm ihtiyacını azaltarak daha sürdürülebilir API evolution sağlar.

Optional Fields

Optional alanlar yeni verilerin mevcut istemcileri zorlamadan eklenmesine imkan verir. İstemci alanın bulunmaması durumunu doğal biçimde ele almalıdır. Server da default davranışı açıkça tanımlamalıdır. Required alan sayısını gereksiz yere artırmak gelecekteki değişiklik seçeneklerini daraltır. Özellikle public API tasarımında gerçekten zorunlu olmayan alanları optional tutmak migration esnekliği sağlar.

Unknown Field Toleransı

Unknown field toleransı istemcinin bilmediği response alanlarını görmezden gelebilmesini sağlar. Bu özellik additive evolution için en değerli compatibility mekanizmalarından biridir. İstemci yalnızca ihtiyaç duyduğu alanları parse ederse server yeni bilgiler ekleyebilir. SDK generator ayarları bu davranışı bozmayacak şekilde seçilmelidir. Contract testleri yeni field eklenmiş response'u eski SDK ile işleyerek toleransı doğrulayabilir.

Unknown Enum Fallback

Unknown enum fallback, gelecekte eklenen enum değerlerinin istemciyi tamamen bozmasını engeller. Örneğin SDK modelinde UNKNOWN veya benzeri güvenli bir fallback değer kullanılabilir. Uygulama bilinmeyen değeri loglayıp kontrollü davranabilir. Böylece server enum kümesini genişletirken eski client'lar çalışmaya devam eder. Bu tasarım özellikle public API ve uzun ömürlü mobil istemciler için güçlü bir koruma sağlar.

Extensible Objects

Extensible object tasarımı veri modelinin yeni alanlarla büyüyebileceğini baştan kabul eder. İstemciler objenin yalnızca bildikleri özelliklerine güvenmeli ve bilinmeyen özellikleri hata saymamalıdır. Bu yapı metadata veya capability benzeri genişleyebilir alanlarda özellikle yararlıdır. Server yeni veri eklerken mevcut contract'ı bozmadan ilerleyebilir. Yine de kritik alanların anlamı değiştirilecekse yeni property veya yeni sürüm tercih edilmelidir.

Open-Ended Unions

Open-ended union yaklaşımı gelecekte yeni variant türlerinin eklenebileceğini kabul eder. İstemcinin bilinmeyen variant için fallback davranışı bulunmalıdır. Sadece bugün bilinen türleri exhaustive şekilde kodlamak uzun vadede kırılganlık yaratır. Schema tasarımı discriminator ve unknown model desteğiyle genişleyebilir hale getirilebilir. SDK generation sürecinde union davranışının hedef dillerde nasıl temsil edildiği ayrıca test edilmelidir.

Default Values

Default değerler optional parameter veya field davranışını öngörülebilir hale getirebilir. Ancak default'ın zaman içinde sessizce değiştirilmesi behavioral breaking change oluşturabilir. Bu nedenle default değer contract ve dokümantasyonda açıkça ifade edilmelidir. Yeni davranış gerekiyorsa explicit parameter veya yeni version üzerinden seçilmesi daha güvenlidir. Böylece istemcinin gönderdiği request ile server'ın hangi davranışı seçtiği anlaşılır hale gelir.

Explicit Ordering Gerektiğinde Sort Parametresi

Sıralamanın iş açısından önemli olduğu endpoint'lerde explicit sort parameter sunmak iyi bir tasarım tercihidir. İstemci böylece backend'in tesadüfi veri tabanı sırasına bağımlı kalmaz. Default sıralama varsa onun da açıkça belgelenmesi gerekir. Yeni sort seçenekleri additive biçimde eklenebilir. Bu yaklaşım pagination, caching ve response karşılaştırmalarında da daha öngörülebilir sonuçlar sağlar.

REST API Versiyonlama Yöntemleri

REST API versioning stratejileri arasında URI path, header, media type, query parameter, tarih tabanlı sürümleme ve capability negotiation gibi farklı yöntemler bulunur. Tek bir yöntemin her API için mutlak biçimde doğru olduğunu söylemek mümkün değildir. Seçim, API'nin public veya internal olması, istemci sayısı, gateway altyapısı, cache davranışı ve developer experience beklentileriyle birlikte yapılmalıdır. URL header ve query parameter API versiyonlama yöntemleri karşılaştırması yapılırken yalnızca görünürlük değil, routing ve operasyonel gözlemlenebilirlik de dikkate alınmalıdır. Benim pratikte en önemli gördüğüm nokta, seçilen yöntemin organizasyon genelinde tutarlı ve açık biçimde uygulanmasıdır.

URI Path Versioning

URI path versioning sürüm bilgisini doğrudan URL yolunda taşır. /api/v1/users gibi adresler sürümü hem geliştirici hem operasyon ekibi için görünür hale getirir. Gateway routing ve log analizi genellikle kolaydır. Dezavantajı aynı kaynak için çok sayıda URL ve büyük sürüm migration projeleri oluşturabilmesidir. Public API'lerde sadeliği nedeniyle sık tercih edilen bir yöntemdir.

Header Versioning

Header versioning sürüm bilgisini özel bir HTTP header içinde taşır. URL kaynak kimliğini korurken contract seçimini request metadata üzerinden yapar. Bu yaklaşım daha temiz URL sağlayabilir fakat manuel testlerde görünürlüğü azaltabilir. Cache ve CDN yapılandırmasında version header'ın cache key'e doğru biçimde dahil edilmesi gerekir. Gateway ve developer tooling desteği yeterliyse güçlü bir seçenek olabilir.

Media-Type Versioning

Media-type versioning genellikle Accept header ve vendor media type kullanarak representation sürümünü seçer. HTTP content negotiation yaklaşımıyla uyumlu bir model sunar. Fakat geliştiricilerin header formatını doğru oluşturması ve dokümantasyon araçlarının bunu rahat göstermesi gerekir. Küçük ekiplerde gereğinden fazla operasyonel yük oluşturabilir. Bu nedenle teknik zarafet ile developer experience arasında dengeli karar verilmelidir.

Query Parameter Versioning

Query parameter versioning, sürümü ?version=2 gibi açık bir URL parametresiyle taşır. Tarayıcı, curl ve manuel testlerde kullanımı oldukça kolaydır. Gateway routing de query parameter üzerinden yapılabilir. Buna karşılık cache davranışı query key normalizasyonuna bağlı olduğundan altyapı ayarları dikkatle kontrol edilmelidir. Public API'lerde açık sözleşme tercih ediliyorsa path kadar yaygın olmasa da pratik bir seçenek olabilir.

Date-Based Versioning

Date-based versioning sürümü bir major numara yerine belirli bir sözleşme tarihiyle ifade eder. Örneğin 2026-08-01 biçimindeki değer hangi davranış setinin seçildiğini açıkça gösterebilir. Bu yaklaşım sık gelişen API'lerde sürüm tarihini daha anlaşılır hale getirir. Ancak her tarihin ayrı contract olmadığı, yalnızca desteklenen version tarihleri bulunduğu açık biçimde belgelenmelidir. Support window politikası tarih tabanlı sürümlemenin vazgeçilmez parçasıdır.

Resource-Level Versioning

Resource-level versioning tüm API yerine belirli kaynak veya operasyonların farklı sürümlere sahip olmasını sağlar. Büyük platformlarda bazı domain'ler daha hızlı gelişirken diğerleri sabit kalabilir. Bu yaklaşım geniş migration projelerini azaltabilir. Buna karşılık client tarafında hangi resource'un hangi sürümde olduğu daha zor takip edilebilir. Version matrix ve güçlü dokümantasyon olmadan yönetim yükü hızla artabilir.

Feature/Capability Negotiation

Capability negotiation istemcinin belirli bir sürüm numarası yerine hangi özellikleri desteklediğini bildirmesini sağlar. Backend kararını client version karşılaştırmalarından ziyade feature set üzerinden verir. Bu model mobil ve uzun ömürlü istemcilerde esneklik sağlayabilir. Fakat capability mapping'in merkezi yönetilmesi ve drift oluşmaması gerekir. Bu yöntem contract versioning'in yerine değil, çoğu durumda onun tamamlayıcısı olarak kullanılmalıdır.

URI Path Versioning

URI path versioning, geliştiricilerin ilk bakışta anlayabildiği en görünür yöntemlerden biridir. Sürüm path içinde bulunduğu için gateway, log, monitoring ve dokümantasyon araçlarında ayrım yapmak kolaydır. Buna karşılık her major sürüm aynı kaynağın farklı URL'lerde temsil edilmesine yol açar. Büyük v2 projelerinde ekipler bazen yalnızca değişen endpoint'ler yerine tüm API'yi yeniden yayınlamaya yönelir. Bu nedenle path versioning seçildiğinde yeni major sürüm açma kriterleri açıkça sınırlandırılmalıdır.

/api/v1/users

/api/v1/users adresi ilk contract sürümünün açık bir örneğidir. İstemci hangi sürümü kullandığını request URL'den kolayca görebilir. Log analizi sırasında da v1 trafiğini filtrelemek basittir. Bu görünürlük migration dashboard oluştururken ciddi kolaylık sağlar. Ancak v1'in ne kadar destekleneceği ayrı bir support policy ile belirtilmelidir.

/api/v2/users

/api/v2/users yeni ve geriye uyumsuz contract'ın paralel olarak sunulmasına imkan verir. V1 ve v2 aynı anda çalışarak client-by-client migration yapılabilir. İki route'un business logic'i mümkün olduğunca ortak canonical model üzerinde tutulmalıdır. Aksi durumda v1 ve v2 kodları zamanla iki ayrı ürün gibi ayrışabilir. Adapter pattern bu ayrışmayı kontrol altında tutmak için yararlı olabilir.

Avantajları

Path versioning'in en büyük avantajı sürüm bilgisinin herkes tarafından kolayca görülebilmesidir. Routing kuralları sade oluşturulabilir ve loglarda sürüm ayrımı zahmetsiz yapılabilir. Dokümantasyon sayfaları URL yapısıyla doğal biçimde eşleştirilebilir. Cache katmanları farklı path'leri doğal olarak ayrı kaynaklar kabul eder. Bu nedenlerle çok sayıda third-party istemciye sahip public API'lerde uygulanması kolay bir modeldir.

Görünürlük

Path içindeki sürüm geliştiriciye request'in hangi contract'a gittiğini doğrudan gösterir. Debug sırasında gizli header aramak gerekmez. Log, tracing ve support kayıtlarında URL tek başına yeterli bağlam sağlayabilir. Developer portal örnekleri de daha kolay anlaşılır. Bu görünürlük yeni entegrasyon yapan ekiplerin hata ayıklama süresini azaltabilir.

Routing kolaylığı

API gateway ve reverse proxy sistemleri path prefix üzerinden kolayca routing yapabilir. V1 ve v2 farklı backend deployment'larına veya adapter katmanlarına yönlendirilebilir. Canary rollout sırasında yalnızca belirli path için trafik kuralları uygulanabilir. Route removal işlemi de merkezi gateway politikasından yönetilebilir. Bu yapı özellikle büyük platformlarda operasyonel kontrolü kolaylaştırır.

Cache kolaylığı

Farklı path'ler çoğu cache sistemi tarafından doğal olarak farklı cache key olarak değerlendirilir. Bu nedenle v1 response'unun yanlışlıkla v2 request'e dönme riski header yöntemine göre daha düşüktür. Yine de query parameter ve authorization gibi diğer cache bileşenleri kontrol edilmelidir. CDN politikaları her version için ayrı yönetilebilir. Cache testleri rollout öncesinde gerçek trafik örnekleriyle çalıştırılmalıdır.

Dokümantasyon

Path versioning dokümantasyonda sürüm ayrımını açıkça göstermeyi kolaylaştırır. Her örnekte kullanılan URL sürüm bilgisini taşır. Version picker ile v1 ve v2 örnekleri rahatça ayrılabilir. SDK snippet'leri de hangi base URL'i kullandığını açıkça gösterebilir. Kullanıcı açısından sürüm seçimi daha görünür ve daha az sürprizli hale gelir.

Dezavantajları

Path versioning'in kolay görünmesine rağmen uzun vadeli maliyetleri bulunur. Aynı kaynak için çok sayıda URL üretilmesi dokümantasyon ve route yönetimini büyütebilir. Ekipler küçük breaking change'ler için bile yeni major path açmaya başlarsa version proliferation oluşur. Büyük v2 migration projeleri aylar sürebilir ve eski sürüm temizliği ertelenebilir. Bu nedenle yöntemin sadeliği güçlü governance ihtiyacını ortadan kaldırmaz.

URL çoğalması

Her major version yeni URL seti oluşturduğunda route sayısı hızla artabilir. Aynı işlevin v1, v2 ve v3 varyasyonları gateway ve monitoring ekranlarını kalabalıklaştırır. Dokümantasyonun hangi sürümü varsayılan göstereceği de önemli hale gelir. Eski URL'lerin ne zaman kaldırılacağı net değilse büyüme kalıcı hale gelir. Maximum concurrent versions politikası bu sorunu sınırlandırabilir.

Büyük v2 migration projeleri

Path tabanlı yeni major version bazen ekipleri tüm API'yi bir kerede yeniden tasarlamaya teşvik eder. Böyle bir proje hem server hem SDK hem istemci tarafında büyük değişiklik paketi yaratır. Migration süresi uzadıkça v1 ve v2 paralel destek maliyeti artar. Daha küçük ve kontrollü breaking change grupları çoğu zaman daha yönetilebilir olur. V2 açmadan önce additive evolution ile çözülemeyen gerçek ihtiyaçlar belirlenmelidir.

Version proliferation

Version proliferation çok sayıda aktif sürümün aynı anda desteklenmesi durumudur. Test matrix, documentation, SDK ve security backport maliyeti her yeni sürümle büyür. Kullanıcılar hangi sürümü seçmeleri gerektiğini anlamakta zorlanabilir. Açık support window ve sunset politikası olmadan bu durum yıllarca devam edebilir. Yeni version açma kararı bu uzun vadeli maliyeti hesaba katmalıdır.

Header-Based Versioning

Header-based versioning URL'i sabit tutarken sözleşme sürümünü request metadata içinde taşır. Bu yaklaşım kaynak adresi ile representation seçimini birbirinden ayırabilir. İyi tasarlandığında gateway routing, SDK ve observability ile rahat çalışır. Buna karşılık manuel testlerde görünürlüğün azalması ve cache yapılandırmasının daha dikkatli yapılması gerekir. Header yöntemini seçen ekiplerin default version davranışını özellikle açık hale getirmesi önemlidir.

Dedicated Version Header

Dedicated version header örneğin API-Version: 2 gibi açık bir alan kullanır. İstemci contract seçimini doğrudan ifade eder. Header'ın adı, formatı ve desteklenen değerleri dokümantasyonda sabit tutulmalıdır. Gateway loglarına bu değer ayrı bir field olarak yazılmalıdır. Böylece usage analytics ve migration takibi kolaylaşır.

Date-Based Header

Date-based header sürümü API-Version: 2026-08-01 gibi bir tarih ile seçebilir. Bu model sürümün hangi contract tarihine karşılık geldiğini açıkça gösterir. Özellikle düzenli değişiklik yapan API'lerde anlaşılır bir evolution modeli sunabilir. Desteklenen tarihler sınırlı ve belgelenmiş olmalıdır. Her request'te rastgele tarih kabul etmek yerine bilinen version snapshot'ları kullanmak daha güvenlidir.

Default Version

Header gönderilmediğinde hangi sürümün kullanılacağı kritik bir tasarım kararıdır. Otomatik olarak en yeni sürümü seçmek eski istemcilerin farkında olmadan breaking change yaşamasına neden olabilir. Daha güvenli seçenek sabit bir default version veya explicit version zorunluluğudur. Default davranış değiştirilecekse bu işlem de migration olarak ele alınmalıdır. Telemetri header göndermeyen istemcileri ayrıca göstermelidir.

Explicit Version Zorunluluğu

Explicit version zorunluluğu her istemcinin hangi contract'ı kullandığını açıkça belirtmesini sağlar. Bu yaklaşım default version belirsizliğini ortadan kaldırır. Yeni sürüm yayınlandığında eski istemciler aynı header değerini göndererek etkilenmeden çalışabilir. Client inventory de version header üzerinden daha doğru oluşturulabilir. Dezavantajı ilk entegrasyon sırasında bir ek ayar gerektirmesidir, fakat uzun vadeli öngörülebilirlik genellikle bu maliyeti karşılar.

Avantajları

Header-based versioning temiz ve sabit URL yapısı sağlar. Sürüm seçimi request metadata olarak ele alındığı için resource identity değişmez. Gateway kuralları version header üzerinden merkezi yönetilebilir. SDK'lar header'ı otomatik ekleyerek geliştiricinin ekstra işlem yapmasını engelleyebilir. Geniş platformlarda version analytics için de güçlü bir sinyal üretir.

Dezavantajları

Header yöntemi browser adres çubuğunda veya basit URL paylaşımında sürüm bilgisini görünmez hale getirir. Debug sırasında request header'larının ayrıca incelenmesi gerekir. CDN veya proxy cache key yanlış yapılandırılırsa farklı sürümlerin response'ları karışabilir. Dokümantasyon araçlarının özel header desteği de developer experience'ı etkileyebilir. Bu nedenle operasyonel altyapı hazır değilse path yönteminden daha fazla disiplin gerektirebilir.

Header Versioning ve HTTP Cache

Header versioning kullanıldığında cache davranışı versioning tasarımının ayrılmaz bir parçası haline gelir. Aynı URL farklı version header değerleriyle farklı response üretebildiği için cache katmanının bu farkı bilmesi gerekir. Aksi durumda v1 için üretilmiş cevap v2 istemcisine dönebilir. Bu hata test ortamında görünmeyip yalnızca CDN veya production proxy üzerinde ortaya çıkabilir. Cache key, Vary ve CDN configuration birlikte tasarlanmalı ve version-aware testlerle doğrulanmalıdır.

Cache Key

Cache key hangi request'lerin aynı cached response'u paylaşacağını belirler. Version header response içeriğini değiştiriyorsa bu header cache key'in bir parçası olmalıdır. Aksi durumda farklı contract'lar aynı cache girdisine eşlenebilir. Gateway ve CDN ürünlerinin default davranışı varsayılmamalı, açıkça test edilmelidir. Version migration sırasında yanlış cache etkisini görmek için v1 ve v2 request'leri paralel çalıştırılabilir.

Vary

Vary response header'ı cache katmanına hangi request header'larının representation seçiminde etkili olduğunu bildirebilir. Version header ile farklı response üretiliyorsa uygun Vary davranışı düşünülmelidir. Fakat tüm cache sistemlerinin aynı şekilde davrandığı varsayılmamalıdır. CDN dokümantasyonu ve gerçek configuration birlikte kontrol edilmelidir. Cache testleri yalnızca origin server üzerinde değil, production'a benzeyen dağıtım yolunda yapılmalıdır.

CDN Configuration

CDN configuration version-aware response serving için doğru cache policy içermelidir. Özel version header cache key'e eklenmiyorsa farklı sürümler birbirinin cevabını görebilir. Bu durum veri şekli ve status code açısından ciddi istemci hatalarına yol açabilir. Configuration değişikliği infrastructure-as-code veya benzeri denetlenebilir bir süreçle yönetilmelidir. Release öncesinde sentetik v1 ve v2 request'leri ile cache doğrulaması yapılması yararlıdır.

Yanlış Sürüm Response'unun Cache'den Dönmesi

Yanlış sürüm response'unun cache'den dönmesi teşhisi zor bir production problemidir. Origin doğru cevap üretirken ara cache eski veya farklı version'a ait representation sunabilir. İstemci bunu schema hatası veya beklenmeyen field değişikliği olarak görebilir. Loglarda cache hit bilgisi ve request version birlikte tutulursa teşhis kolaylaşır. Bu risk header versioning tasarımının başından itibaren test planına eklenmelidir.

Cache Testleri

Cache testleri aynı endpoint'e farklı version değerleriyle ardışık request göndererek başlamalıdır. Her response'un doğru contract'a ait olduğu doğrulanmalıdır. Cache hit ve miss durumları ayrı senaryolar olarak çalıştırılmalıdır. CDN invalidation ve rollout sonrasında da aynı testler tekrarlanmalıdır. Böylece cache'in API versioning davranışını bozmadığı release gate seviyesinde güvence altına alınabilir.

Media-Type Versioning

Media-type versioning, representation sürümünü HTTP content negotiation mekanizması üzerinden seçer. Teknik olarak güçlü ve standart HTTP kavramlarıyla uyumlu bir yaklaşım sunabilir. Ancak API tüketicilerinin vendor media type formatlarını anlaması ve doğru header göndermesi gerekir. SDK veya güçlü developer tooling yoksa manuel kullanım zorlaşabilir. Bu nedenle yöntem seçilirken yalnızca protokol uyumu değil, hedef geliştirici kitlesinin deneyimi de değerlendirilmelidir.

Accept Header

Accept header istemcinin hangi representation türünü almak istediğini bildirir. Version bilgisi de media type içine gömülerek contract seçimi yapılabilir. Server uygun representation'ı seçerken content negotiation kurallarını uygular. İstemcinin yanlış veya eksik header göndermesi durumunda default davranış net olmalıdır. Monitoring sistemleri seçilen media type sürümünü ayrıca loglamalıdır.

Vendor Media Types

Vendor media type API'ye özel representation formatını tanımlamak için kullanılabilir. Sürüm bu media type'ın bir parçası olarak ifade edilebilir. Teknik olarak esnek olsa da geliştiricinin doğru syntax'ı öğrenmesini gerektirir. Dokümantasyon ve SDK desteği bu ek yükü büyük ölçüde azaltabilir. Public API'de kullanılacaksa curl örnekleri ve hata mesajları açık olmalıdır.

Content Negotiation

Content negotiation aynı resource için farklı representation seçeneklerini yönetir. Versioning bu mekanizmayla birleştirildiğinde URL sabit kalabilir. Server request header'ına göre doğru contract'ı üretir. Cache katmanları representation seçimini dikkate alacak şekilde yapılandırılmalıdır. Ayrıca unsupported media type durumlarında geliştiriciye anlaşılır hata bilgisi verilmelidir.

Avantajları

Media-type versioning resource URL'lerinin sürümler arasında değişmemesini sağlar. Representation değişimi HTTP header üzerinden açıkça kontrol edilir. Bazı API tasarımlarında bu ayrım kavramsal olarak oldukça temizdir. Aynı endpoint farklı contract'ları sunarken routing merkezi tutulabilir. Güçlü SDK ve dokümantasyon desteği varsa geliştirici açısından da rahat kullanılabilir.

Developer Experience Sorunları

Developer experience açısından media-type syntax'ı path versioning'e göre daha az görünür olabilir. Basit browser testi yapmak isteyen geliştirici header eklemek zorundadır. Hatalı Accept formatları anlaşılması zor 406 veya benzeri sonuçlara yol açabilir. API explorer ve SDK'ların header'ı otomatik yönetmesi bu yükü azaltır. Hedef kullanıcı kitlesi teknik olarak çok çeşitli ise daha açık bir yöntem tercih etmek daha kolay olabilir.

Query Parameter Versioning

Query parameter versioning sürüm bilgisini URL query bölümünde taşır ve kullanımı oldukça görünür hale getirir. ?version=2 gibi bir yapı curl, tarayıcı ve API test araçlarında kolayca denenebilir. Gateway routing de çoğu ortamda query değerine göre yapılabilir. Buna karşılık cache key normalizasyonu ve URL paylaşımıyla ilgili kurallar açık olmalıdır. Bu yöntem özellikle küçük, kontrollü veya manuel test kolaylığının önemli olduğu API'lerde pratik olabilir.

?version=2

?version=2 sürüm seçimini açık ve kolay okunur hale getirir. İstemci hangi contract'ı istediğini URL üzerinden belirtir. Server query değeri doğrultusunda doğru adapter veya handler'a yönlendirebilir. Desteklenmeyen version için yapılandırılmış hata dönülmelidir. Default version kullanılıyorsa header yönteminde olduğu gibi davranışın sabit ve belgelenmiş olması gerekir.

Manuel Test Kolaylığı

Query parameter yönteminin önemli avantajlarından biri manuel test kolaylığıdır. URL'i doğrudan değiştirerek v1 ve v2 sonuçları karşılaştırılabilir. Support ekipleri de request örneğini daha kolay paylaşabilir. Bu görünürlük debugging süresini azaltabilir. Ancak hassas bilgilerin query parameter olarak taşınmaması gerektiği genel HTTP güvenlik prensibi sürüm bilgisinden ayrı değerlendirilmelidir.

Cache Davranışı

Çoğu cache sistemi query string'i cache key'in parçası olarak kullanır, ancak configuration farkları olabilir. Bazı CDN politikaları belirli query parameter'ları ignore edebilir veya normalize edebilir. Bu nedenle version parametresinin cache ayrımına dahil olduğu doğrulanmalıdır. V1 ve v2 response'ları ardışık testlerle kontrol edilmelidir. Cache davranışı varsayıma bırakılmamalıdır.

API Gateway Routing

API gateway query parameter değerine göre farklı backend veya adapter'a routing yapabilir. Bu sayede migration logic business service'in dışına taşınabilir. Central logging de version değerini otomatik kaydedebilir. Ancak gateway rule sayısı arttıkça configuration yönetimi zorlaşabilir. Version policy ve route tanımları aynı source control sürecinde tutulmalıdır.

Ne Zaman Kullanılmalı?

Query parameter yöntemi basit entegrasyon, güçlü manuel test ihtiyacı veya sınırlı istemci sayısı olan projelerde düşünülebilir. Public API için kullanılacaksa cache ve documentation davranışı iyi tasarlanmalıdır. Çok büyük API portföylerinde path veya header kadar yaygın olmayabilir. Yine de teknik olarak doğru uygulandığında işlevsel bir çözüm sunar. Asıl önemli olan yöntemden çok, seçimin tutarlı uygulanması ve migration politikasıyla desteklenmesidir.

Calendar Versioning Nedir?

Calendar versioning API sözleşmesini sıra numarası yerine tarih üzerinden tanımlayan bir versioning modelidir. Tarih, istemciye kullandığı davranış setinin ne zaman oluşturulduğunu açıkça gösterir. Bu model sık güncellenen API'lerde major version numaralarının anlamını tartışmak yerine contract snapshot tarihine odaklanabilir. Ancak tarih tek başına destek süresini söylemez. Bu nedenle calendar versioning daima support window, deprecation ve migration politikasıyla birlikte kullanılmalıdır.

Tarih Tabanlı API Sürümleri

Tarih tabanlı API sürümleri belirli bir contract snapshot'ını bir takvim tarihiyle tanımlar. İstemci aynı tarih değerini kullandığı sürece davranışın öngörülebilir kalması beklenir. Yeni özellikler daha yeni version tarihine eklenebilir. Server eski tarihleri belirli support window boyunca destekleyebilir. Böylece API evolution sıklığı ile istemci migration hızı arasında esnek bir denge kurulabilir.

YYYY-MM-DD

YYYY-MM-DD biçimi tarih tabanlı sürümü kolay okunur ve sıralanabilir hale getirir. Örneğin 2026-08-01 açık bir contract tarihini gösterebilir. Bu değer header veya başka bir version seçim mekanizmasıyla taşınabilir. API yalnızca resmi olarak yayınlanan tarihleri kabul etmelidir. Dokümantasyonda her version tarihinin değişiklik özeti ayrıca sunulmalıdır.

Major Version Numarasından Farkı

Major version numarası genellikle büyük breaking change dönemlerini temsil eder. Calendar versioning ise sözleşmenin yayın zamanını doğrudan görünür kılar. Bu nedenle değişiklik ritmi daha düzenli ve sık olan API'lerde tercih edilebilir. Fakat tarih kullanmak breaking change analizini gereksiz hale getirmez. İstemcinin bir tarihten diğerine geçerken hangi farklarla karşılaşacağı yine migration guide içinde açıklanmalıdır.

Sürümün Ne Zaman Çıktığını Açıkça Gösterme

Tarih tabanlı sürümün güçlü taraflarından biri sürüm zamanını isminden anlayabilmektir. Geliştirici v17 yerine doğrudan yayın tarihini görür. Support ekipleri de çok eski contract kullanan istemcileri daha hızlı fark edebilir. Bu bilgi usage analytics ile birleştirildiğinde migration önceliği belirlemek kolaylaşır. Ancak release tarihi ile sunset tarihi birbirine karıştırılmamalıdır.

Support Window ile Birlikte Kullanım

Calendar versioning açık support window olmadan hızla çok sayıda aktif tarihe dönüşebilir. Örneğin son belirli sayıda contract tarihinin desteklenmesi veya belirli süre garantisi verilebilir. İstemciler yeni version tarihine geçmek için öngörülebilir zaman kazanır. Eski tarihler de deprecation ve sunset sürecine alınabilir. Bu politika baştan yayınlandığında kullanıcıların migration planlaması kolaylaşır.

Semantic Versioning REST API'lerde Kullanılmalı mı?

Semantic Versioning, yazılım paketlerinde MAJOR, MINOR ve PATCH değişikliklerini ifade etmek için çok kullanışlıdır. REST API tarafında ise her server değişikliğini 1.3.7 gibi dış contract sürümüne dönüştürmek çoğu zaman gereksiz yük oluşturur. API sürekli çalışan bir servis olduğu için package release mantığıyla birebir aynı ihtiyaçlara sahip değildir. Semantic Versioning SDK paketlerinde çok daha doğal kullanılabilir. API contract için major version veya calendar version gibi daha sade modeller genellikle geliştirici deneyimini iyileştirir.

MAJOR

MAJOR sürüm geriye uyumsuz değişiklikleri ifade etmek için güçlü bir kavramdır. REST API'de v1'den v2'ye geçiş bu mantıkla ilişkilendirilebilir. Ancak her küçük davranış farkı yeni major sürüm olmamalıdır. Yeni major version uzun süreli support ve migration maliyeti oluşturur. Bu nedenle gerçekten mevcut contract içinde çözülemeyen değişiklikler için kullanılmalıdır.

MINOR

MINOR sürüm geriye uyumlu yeni özellikleri ifade eder. SDK paketlerinde yeni method veya model desteği için oldukça faydalıdır. API server tarafında ise istemcinin her minor contract değerini göndermesi gerekli olmayabilir. Additive evolution aynı major version altında devam edebilir. Changelog yeni özellikleri tarih ve release bilgisiyle ayrıca gösterebilir.

PATCH

PATCH sürümü geriye uyumlu bug fix'leri temsil eder. SDK paketlerinde bu ayrım dependency management açısından değerlidir. Server API için ise bug fix çoğu zaman istemcinin contract version seçiminden bağımsız yayınlanır. Her patch'i URL veya header version olarak expose etmek gereksiz version sayısı yaratabilir. Operasyonel release version ile public API contract version bu nedenle ayrı tutulmalıdır.

Library Versioning ile API Versioning Farkı

Library versioning kullanıcının belirli bir paketi install etmesine dayanır. API versioning ise istemcinin çalışan bir remote service sözleşmesini seçmesine dayanır. Paket kullanıcıları upgrade zamanını büyük ölçüde kontrol ederken server değişiklikleri merkezi olarak yayınlanır. Bu farklılık release ve compatibility stratejilerini etkiler. SDK Semantic Versioning kullanırken API contract daha farklı bir version modeli kullanabilir.

Neden Her API Değişikliğini 1.3.7 Olarak Expose Etmek Gerekmeyebilir?

Her API değişikliğini public contract version'a dönüştürmek istemcilerin gereksiz sürüm takibi yapmasına neden olur. Bug fix veya additive field için istemcinin yeni bir version seçmesi çoğu zaman değer üretmez. Bunun yerine server aynı desteklenen contract'ı güvenli biçimde evolve edebilir. Changelog değişiklik görünürlüğünü sağlar. Public version yalnızca istemci davranışını gerçekten ayırmak gerektiğinde kullanılmalıdır.

Hangi Versioning Stratejisi Seçilmeli?

Versioning stratejisi seçerken hedef istemci kitlesi, release kontrolü, cache altyapısı, gateway yetenekleri ve support modeli birlikte değerlendirilmelidir. Çok sayıda bağımsız third-party client bulunan public API ile aynı ekip tarafından kontrol edilen internal API'nin ihtiyaçları aynı değildir. Path versioning görünürlük, header versioning contract seçimi ve date-based model düzenli evolution konusunda güçlü avantajlar sunabilir. Tek bir kurumsal standart belirlemek operasyonel tutarlılığı artırır, ancak gerekli durumlarda domain ihtiyaçlarına göre kontrollü istisnalar tanımlanabilir. REST API geliştirme ve backend danışmanlığı yakınımda gibi bir ihtiyaç arayan ekipler için de önce teknoloji seçmek yerine mevcut client ownership ve migration sürecini analiz etmek daha sağlıklı bir başlangıçtır.

Public API

Public API'lerde istemci sayısı ve çeşitliliği yüksek olduğu için açık versioning ve uzun support window önemlidir. Path veya explicit header yaklaşımı geliştiriciye hangi contract'ı kullandığını net biçimde göstermelidir. Deprecation duyuruları birden fazla kanaldan yapılmalıdır. SDK ve migration dokümantasyonu public kullanıcıların kendi takvimlerinde geçiş yapabilmesini sağlamalıdır. Kullanım ölçümü olmadan eski sürüm kapatılmamalıdır.

Internal API

Internal API'lerde consumer owner'ları biliniyorsa daha koordineli migration yapılabilir. Bu durum versioning ihtiyacını tamamen ortadan kaldırmaz. Çok sayıda microservice bağımlılığı yine breaking change riskini büyütebilir. Consumer-driven contract testleri ve dependency mapping burada çok değerlidir. Daha kısa support window mümkün olsa bile değişiklik takvimi ekiplerle açıkça paylaşılmalıdır.

Partner API

Partner API'lerde az sayıda fakat iş açısından kritik entegrasyon bulunabilir. Her partner'ın release ve test süreci farklı olabilir. Bu nedenle client inventory, owner ve contact bilgisi güncel tutulmalıdır. Migration döneminde sandbox veya test endpoint sağlamak geçiş riskini azaltır. Support SLA ve sunset takvimi partner sözleşmeleriyle uyumlu planlanmalıdır.

Mobile Backend

Mobile backend versioning özellikle kullanıcıların eski uygulama sürümlerini uzun süre kullanabilmesi nedeniyle farklı zorluklar taşır. Backend her app release'ini zorunlu olarak kontrol edemez. Client version, platform ve capability bilgisi response shaping için kullanılabilir. Fakat kod içine dağılmış version check'ler uzun vadede bakım yükü oluşturur. Version-to-feature mapping bu nedenle merkezi tutulmalıdır.

Microservices

Microservice API'lerinde versioning kararları organizasyonel bağımlılıklarla doğrudan ilişkilidir. Service owner ile consumer owner aynı ekip olmayabilir. Contract testleri ve dependency graph hangi değişikliğin hangi servisi etkilediğini göstermelidir. Servis keşfi ve servisler arası iletişim konusundaki tamamlayıcı içerik için https://www.diyarbakiryazilim.com.tr/posts/mikroservislerde-servis-kesfi-service-discovery-ve-yonetimi adresindeki rehber incelenebilir. Versioning burada yalnızca HTTP formatı değil, ekipler arası coordination contract olarak görülmelidir.

Çok Sayıda Third-Party Client

Çok sayıda third-party client bulunan API'lerde release kontrolü sağlayıcının dışındadır. Bu nedenle geriye uyumluluk ve uzun migration window daha değerlidir. İstemci kimliği, SDK version ve last-seen bilgisi toplanmalıdır. Deprecation yalnızca dokümantasyon notu olarak bırakılmamalı, runtime sinyalleri ve doğrudan iletişimle desteklenmelidir. Sunset kararı aktif client sayısı ve trafik oranıyla doğrulanmalıdır.

Az Sayıda Kontrol Edilen Client

Az sayıda ve aynı organizasyon tarafından kontrol edilen client'larda migration daha hızlı yapılabilir. İstemci ekipleri doğrudan koordine edilebilir ve release takvimleri eşleştirilebilir. Yine de breaking change'in testsiz yayınlanması doğru değildir. Contract testleri ve canary migration riski azaltır. Kısa support window kullanılacaksa bunun ekipler tarafından bilinen bir politika olması gerekir.

API Version ile SDK Version Aynı Şey midir?

API version ile SDK version aynı kavram değildir ve aynı numarayı kullanmaları gerekmeyebilir. API version remote contract'ı, SDK version ise dağıtılan client paketinin release yaşam döngüsünü ifade eder. API değişmeden SDK'da bug fix yapılabilir ve yeni package version yayınlanabilir. Benzer biçimde aynı API v2'yi destekleyen SDK'nın kendi major version'ı farklı olabilir. Bu ayrım dokümantasyonda açık tutulursa istemcilerin hangi paketle hangi contract'ın desteklendiğini anlaması kolaylaşır.

API Contract Version

API contract version server'ın hangi request ve response davranışını sunduğunu tanımlar. Path, header veya tarih değeri ile seçilebilir. Bu sürümün support ve sunset politikası bulunmalıdır. İstemcinin hangi contract'ı kullandığı monitoring sisteminde görünür olmalıdır. Contract version operasyonel deployment numarasından bağımsız tutulabilir.

SDK Package Version

SDK package version geliştiricinin package manager üzerinden yüklediği client kütüphanesinin sürümüdür. Semantic Versioning bu alanda doğal biçimde kullanılabilir. Yeni helper method, bug fix veya runtime desteği package version'ı değiştirebilir. API contract aynı kalırken birçok SDK release'i yapılabilir. Compatibility matrix bu ilişkiyi netleştirir.

SDK Bug-Fix Release

SDK bug fix server API'de herhangi bir değişiklik olmadan yayınlanabilir. Serialization hatası, retry davranışı veya documentation comment düzeltmesi buna örnek olabilir. Böyle bir release API version değişikliği gerektirmez. Package PATCH sürümü artırılabilir. Release notes hangi kullanıcıların upgrade etmesi gerektiğini açıkça belirtmelidir.

API Değişmeden SDK Major Version Çıkabilmesi

SDK'nın kendi public interface'inde breaking change yapılırsa API aynı kalsa bile yeni major package version gerekebilir. Method isimlerinin değiştirilmesi veya runtime requirement yükseltilmesi buna örnektir. Bu durum API v2 ile SDK v2'nin zorunlu olarak aynı anlamı taşımadığını gösterir. İsimlendirme çakışması geliştiricilerin yanlış varsayım yapmasına yol açabilir. Dokümantasyonda API ve SDK version alanları ayrı gösterilmelidir.

İsimlendirmede Karışıklığı Önlemek

İsimlendirme karışıklığını önlemek için dokümantasyon açık terimler kullanmalıdır. Örneğin “API v2” ile “TypeScript SDK 4.1.0” ayrı biçimde yazılabilir. Compatibility table hangi kombinasyonların desteklendiğini gösterir. Release notes da değişikliğin API contract mı yoksa yalnızca SDK mı olduğunu belirtmelidir. Bu küçük ayrım support taleplerini ve migration hatalarını ciddi biçimde azaltabilir.

SDK Versioning Nasıl Tasarlanmalı?

SDK versioning, API'nin geliştirici deneyimini doğrudan etkileyen ayrı bir ürün yaşam döngüsü olarak ele alınmalıdır. Semantic Versioning, package manager deprecation, runtime desteği ve API compatibility matrix bu yaşam döngüsünün parçalarıdır. SDK'nın API'den daha kırılgan hale gelmesi engellenmelidir. Özellikle unknown enum, optional field ve yeni response alanları için forward compatibility testleri yapılmalıdır. İyi tasarlanmış SDK politikası API migration sürecini önemli ölçüde kolaylaştırır.

Semantic Versioning

SDK paketleri için Semantic Versioning kullanıcı beklentisini netleştirir. MAJOR breaking SDK interface değişikliği, MINOR geriye uyumlu özellik ve PATCH bug fix için kullanılabilir. Bu model dependency manager'larla iyi çalışır. API contract version ile birebir eşleşmesi gerekmez. Release notes hangi API sürümlerinin desteklendiğini ayrıca belirtmelidir.

Breaking SDK Change

Breaking SDK change mevcut uygulama kodunun upgrade sonrasında derlenmemesine veya farklı davranmasına neden olabilir. Method rename, type change veya required constructor parameter buna örnektir. Böyle değişiklikler mümkün olduğunca deprecation dönemiyle hazırlanmalıdır. Replacement method önce eklenip eski method uyarı vermeye başlayabilir. Major package release migration notes ile birlikte yayınlanmalıdır.

API Compatibility Matrix

Compatibility matrix hangi SDK sürümünün hangi API version ile çalıştığını gösterir. Özellikle birden fazla aktif API ve SDK major sürümü varsa bu tablo büyük değer sağlar. CI testleri matrix'teki desteklenen kombinasyonları otomatik doğrulayabilir. EOL olan kombinasyonlar açıkça işaretlenmelidir. Böylece geliştirici upgrade sırasında rastgele deneme yapmak yerine desteklenen yolu izler.

Minimum Supported API Version

SDK belirli bir minimum API version gerektirebilir. Bu gereksinim package dokümantasyonunda açıkça belirtilmelidir. SDK startup veya request sırasında çok eski server sürümünü algıladığında anlaşılır uyarı verebilir. Compatibility testleri minimum sınırın gerçekten çalıştığını doğrulamalıdır. Bu yaklaşım eski contract kodunun SDK içinde sonsuza kadar taşınmasını önler.

SDK EOL Policy

SDK EOL policy hangi package major sürümlerinin ne kadar süre destekleneceğini tanımlar. Security patch, runtime uyumluluğu ve bug fix kapsamı açık olmalıdır. Kullanıcılar destek sona ermeden önce yeni SDK'ya geçiş için yeterli zaman kazanmalıdır. Deprecated package sürümleri package manager seviyesinde de işaretlenebilir. EOL tarihi API sunset takvimiyle uyumlu tutulmalıdır.

Package Manager Deprecation

Package manager deprecation eski SDK sürümlerini kullanan geliştiricilere doğrudan uyarı gösterebilir. Bu kanal yalnızca blog veya e-posta duyurusuna göre daha yakın bir temas noktasıdır. Mesaj yeni package version ve migration dokümantasyonunu belirtmelidir. Kritik güvenlik durumlarında uyarının görünürlüğü artırılabilir. Package deprecation, runtime API deprecation sinyallerinin tamamlayıcısı olarak kullanılmalıdır.

İstemci Yönetimi Nedir?

İstemci yönetimi API'yi kullanan uygulamaların kim olduğunu, hangi sürümü kullandığını ve migration sorumluluğunun kimde bulunduğunu bilmektir. Versioning politikasının çalışması için yalnızca server route'larını yönetmek yeterli değildir. Client ID, application owner, team, SDK version ve last-seen verisi merkezi bir inventory içinde tutulmalıdır. Bu envanter deprecation döneminde kiminle iletişim kurulacağını ve hangi client'ın risk taşıdığını gösterir. API versiyon değişikliklerinde backward compatibility deprecation ve istemci migration yönetimi açısından en fazla değer sağlayan pratiklerden biri, bu envanteri version yayınlanmadan önce hazırlamaktır.

API Consumer Envanteri

API consumer inventory hangi uygulamaların API'yi aktif olarak kullandığını gösteren merkezi listedir. İstemci adı, owner, version ve iletişim bilgileri burada tutulabilir. Envanter yalnızca manuel spreadsheet değil, gateway telemetry ile beslenen canlı bir sistem de olabilir. Deprecated sürüm kullanımını client bazında göstermek migration sürecini hızlandırır. Güncel olmayan inventory sunset kararlarını riskli hale getirir.

Client ID

Client ID her consumer'ı teknik olarak ayırt etmeye yarayan önemli bir sinyaldir. Request loglarında version ile birlikte tutulduğunda hangi istemcinin hangi contract'ı kullandığı görülebilir. Rate limit, migration ve support süreçleri de aynı kimlik üzerinden yönetilebilir. Client ID kişisel veri yerine uygulama kimliğini temsil edecek biçimde tasarlanmalıdır. Kimliği olmayan anonim trafik migration yönetimini zorlaştırır.

Application ID

Application ID daha geniş uygulama seviyesinde tüketiciyi tanımlayabilir. Bir uygulamanın birden fazla deployment veya client credential'ı bulunabilir. Bu kimlikler merkezi inventory içinde aynı application altında gruplanabilir. Böylece migration owner ve iş kritikliği doğru bağlamda izlenebilir. Dashboard metrikleri hem client hem application seviyesinde sunulabilir.

Owner

Owner, migration kararlarından sorumlu kişi veya teknik sorumluluk alanını gösterir. Sadece uygulama adını bilmek deprecation döneminde yeterli olmaz. Doğrudan ulaşılabilecek bir owner tanımlamak iletişim süresini kısaltır. Owner değiştiğinde inventory güncellenmelidir. Kurumsal API'lerde sahipliği olmayan istemciler ayrı risk kategorisinde izlenebilir.

Team

Team bilgisi istemcinin organizasyon içindeki sahipliğini daha kalıcı biçimde tanımlar. Bireysel owner değişse bile ekip bilgisi devam edebilir. Migration dashboard ilgili ekiplerin kalan işlerini gösterebilir. Support veya platform ekipleri kritik client'ları team bazında takip edebilir. Bu yaklaşım özellikle internal microservice ekosistemlerinde oldukça yararlıdır.

Contact

Contact bilgisi deprecation ve sunset duyurularının doğru kişiye ulaşmasını sağlar. E-posta, ekip kanalı veya destek sistemi gibi birden fazla kanal tutulabilir. Third-party partner'larda ticari ve teknik contact ayrı olabilir. İletişim bilgileri düzenli olarak doğrulanmalıdır. Eski contact verisi en iyi migration planını bile etkisiz hale getirebilir.

Current API Version

Current API version istemcinin bugün hangi contract'ı kullandığını gösterir. Bu veri manuel beyana değil mümkün olduğunca gerçek trafik loglarına dayanmalıdır. Son görülme tarihi ile birlikte değerlendirildiğinde aktif ve terk edilmiş client'lar ayrılabilir. Migration dashboard v1 ve v2 dağılımını bu bilgiden üretir. Sunset kararı için en kritik metriklerden biridir.

SDK Version

SDK version istemcinin hangi client package sürümünü kullandığını gösterir. Aynı API version üzerinde eski SDK'lar farklı riskler taşıyabilir. Security fix veya deserialization problemi nedeniyle SDK migration da gerekebilir. Telemetry mümkünse SDK adı ve version bilgisini standart user-agent veya ayrı header ile taşımalıdır. Bu veri compatibility matrix ve support politikasıyla birleştirilebilir.

Son Görülme Tarihi

Son görülme tarihi bir istemcinin API'yi en son ne zaman kullandığını gösterir. Uzun süredir trafik üretmeyen client'ların aktif olup olmadığı bu veriyle değerlendirilebilir. Ancak seyrek çalışan aylık iş akışları yanlışlıkla terk edilmiş kabul edilmemelidir. Gözlem süresi client kullanım modeline göre seçilmelidir. Sunset öncesinde last-seen analizi kritik istemcilerin gözden kaçmasını engeller.

İstemci Türleri Neden Ayrı Yönetilmelidir?

Her istemci aynı release kontrolüne ve migration hızına sahip değildir. Web client birkaç dakika içinde deploy edilebilirken mobil uygulamanın kullanıcı cihazında güncellenmesi haftalar veya aylar sürebilir. Partner entegrasyonu ayrı change-management süreçlerinden geçebilir, IoT cihazı ise yıllarca aynı firmware ile çalışabilir. Bu nedenle API support policy tek bir migration süresi varsaymamalıdır. Client type segmentasyonu migration planının gerçek koşullara göre tasarlanmasını sağlar.

Web Client

Web client genellikle server veya CDN üzerinden merkezi olarak güncellenebildiği için hızlı migration yapabilir. Aynı organizasyon tarafından kontrol ediliyorsa API ve frontend release'leri koordine edilebilir. Canary rollout ve feature flag kullanmak oldukça kolaydır. Bu nedenle support window diğer client türlerine göre daha kısa olabilir. Yine de cached asset veya açık browser session'larının eski kod çalıştırabileceği dikkate alınmalıdır.

Mobile Client

Mobile client release'i app store dağıtımı ve kullanıcı güncelleme davranışına bağlıdır. Backend yeni sürümü yayınlasa bile eski uygulamalar uzun süre trafik üretmeye devam eder. Minimum supported app version ve capability mapping bu nedenle önemlidir. API response shaping doğrudan version check'lerle her yere dağılmamalıdır. Uzun kuyruklu version dağılımı göz önünde bulundurularak migration window planlanmalıdır.

Backend Integration

Backend integration genellikle otomatik ve yüksek trafikli iş akışlarını temsil eder. Değişiklik yanlış yönetildiğinde geniş operasyonel etki oluşabilir. Buna karşılık owner ve deployment pipeline biliniyorsa migration kontrollü biçimde yapılabilir. Contract testleri bu istemci türünde güçlü koruma sağlar. Kritik entegrasyonlar sunset readiness değerlendirmesinde yüksek öncelik almalıdır.

Partner Integration

Partner integration organizasyon dışındaki bir ekibin release takvimine bağlı olabilir. Test ortamı, teknik contact ve support SLA migration sürecinin parçası olmalıdır. Partner'ın yeni contract'ı doğrulaması için yeterli zaman verilmelidir. Usage telemetry partner bazında ayrılabilmelidir. Kritik iş ortakları için doğrudan outreach genel e-posta duyurusundan daha etkili olur.

IoT Client

IoT client'lar firmware güncellemesinin zor veya pahalı olması nedeniyle uzun support ihtiyacı doğurabilir. Bazı cihazlar yıllarca aynı API contract'ı kullanabilir. Bu durum versioning ve security politikalarının cihaz yaşam döngüsüyle birlikte tasarlanmasını gerektirir. Capability negotiation ve compatibility layer bazı senaryolarda yararlı olabilir. Yeni cihaz sürümlerinde eski teknik borcun tekrarlanmaması için minimum contract standardı belirlenmelidir.

CLI

CLI araçları kullanıcı makinelerinde farklı sürümlerde uzun süre kalabilir. Package veya binary auto-update yoksa eski CLI API trafiği üretmeye devam edebilir. User-agent içine CLI version eklemek usage analytics için faydalıdır. Deprecated API kullanıldığında terminalde anlaşılır warning gösterilebilir. Yeni CLI sürümüne yönlendiren migration mesajı geçiş hızını artırır.

Third-Party Script

Third-party script çoğu zaman resmi SDK kullanmadan doğrudan HTTP çağrısı yapar. Bu nedenle package deprecation sinyalleri bu istemcilere ulaşmayabilir. Client ID, version header ve developer contact bilgisi daha önemli hale gelir. Basit curl veya script örnekleri migration guide içinde verilmelidir. Bilinmeyen script trafiği varsa sunset öncesinde telemetry detaylandırılmalıdır.

AI Agent

AI agent API'yi tool veya function çağrısı olarak kullanabilir ve schema değişikliklerine farklı biçimde tepki verebilir. Tool description, validation ve response parsing davranışı contract'ın parçası haline gelir. Agent'ın kullandığı API version ve tool schema izlenmelidir. Yeni contract önce kontrollü test senaryolarında doğrulanmalıdır. Özellikle hata yapıları ve required field değişiklikleri agent davranışını etkileyebileceği için migration planına dahil edilmelidir.

First-Party ve Third-Party Client Arasındaki Fark

First-party client sağlayıcının doğrudan kontrol ettiği uygulamayı, third-party client ise bağımsız bir kullanıcı veya kurum tarafından yönetilen entegrasyonu ifade eder. Bu ayrım API migration süresini belirleyen en önemli faktörlerden biridir. First-party uygulamada release planı koordine edilebilirken third-party istemcide yalnızca iletişim ve support politikasıyla yönlendirme yapılabilir. Bu nedenle breaking change riski, SLA ve sunset süresi farklı tasarlanmalıdır. İyi client inventory bu iki grubu ayrı göstermelidir.

Release Kontrolü

First-party client release'i aynı organizasyon tarafından planlanabilir. Backend ve istemci değişiklikleri aynı sprint veya rollout içinde koordine edilebilir. Third-party client'ta ise release tarihi sağlayıcının kontrolünde değildir. Bu nedenle daha uzun migration window gerekir. Version policy bu kontrol farkını açıkça hesaba katmalıdır.

Migration Hızı

First-party istemciler genellikle daha hızlı migrate edilebilir. Otomatik testler, ortak repository veya koordineli ekipler geçişi hızlandırır. Third-party istemciler farklı önceliklere ve release süreçlerine sahip olabilir. Kullanım yoğunluğu aynı olsa bile migration süresi ciddi biçimde değişebilir. Sunset tarihi belirlenirken en yavaş kritik consumer dikkate alınmalıdır.

İletişim Kanalı

First-party client owner'larına iç ekip kanalları üzerinden doğrudan ulaşılabilir. Third-party client için developer portal, e-posta ve support outreach gerekebilir. Runtime deprecation header her iki grup için de teknik sinyal sağlar. İletişimin tek kanala bağlı kalmaması önemlidir. Kritik migration mesajları tekrar eden ve takip edilebilir bir süreçle gönderilmelidir.

Support SLA

Third-party ve partner API'lerde support SLA migration takvimini etkileyebilir. Büyük müşteriler belirli notice period bekleyebilir. Internal client'larda daha kısa süre mümkün olsa bile hizmet kritikliği dikkate alınmalıdır. SLA ile teknik support window çelişmemelidir. Versioning policy hazırlanırken bu operasyonel yükümlülükler önceden incelenmelidir.

Breaking Change Riski

Third-party client davranışını tam olarak bilmek zor olduğu için breaking change riski daha yüksektir. First-party codebase üzerinde static analysis veya doğrudan test yapılabilir. Dış istemcilerde telemetry ve contract kullanım verileri daha önemli hale gelir. Unknown dependency riski geniş public API'lerde özellikle yüksektir. Bu nedenle additive evolution ve uzun deprecation süresi dış kullanıcılar için daha değerlidir.

Mobil İstemciler API Versioning'i Neden Zorlaştırır?

Mobil istemciler backend ekibinin release sonrasında client upgrade'i zorunlu olarak kontrol edememesi nedeniyle API versioning'i zorlaştırır. Uygulama mağazası süreci, kullanıcıların güncellemeyi ertelemesi ve eski işletim sistemleri version dağılımını uzatır. Backend aynı anda çok sayıda app version ile uyumlu kalmak zorunda olabilir. Bu nedenle mobile API contract tasarımı forward compatibility ve capability yaklaşımına daha fazla ihtiyaç duyar. Minimum supported app version yalnızca zorunlu durumlarda ve açık kullanıcı iletişimiyle uygulanmalıdır.

App Store Release Süreci

Mobil release backend deployment kadar anlık değildir. İnceleme, staged rollout ve mağaza dağıtımı geçiş süresini uzatabilir. Bir API breaking change'i mobil release ile tam aynı anda zorunlu kılmak risklidir. Önce backend'in yeni ve eski istemciyi paralel desteklemesi daha güvenlidir. Client adoption yeterli seviyeye ulaştığında eski davranışın sunset süreci başlatılabilir.

Kullanıcıların Güncelleme Yapmaması

Bazı kullanıcılar uygulamalarını haftalar veya aylar boyunca güncellemez. Bu nedenle yeni mobile release yayınlamak eski client trafiğini hemen ortadan kaldırmaz. Backend usage analytics app version dağılımını düzenli takip etmelidir. Kritik olmayan değişikliklerde uzun compatibility window tercih edilebilir. Zorunlu upgrade gerekiyorsa kullanıcı deneyimi ve iş sürekliliği birlikte değerlendirilmelidir.

Eski İşletim Sistemleri

Eski işletim sistemi kullanan cihazlar yeni uygulama sürümünü yükleyemeyebilir. Bu kullanıcılar eski app ve eski API contract'a bağlı kalabilir. Minimum runtime desteği product policy içinde açıkça tanımlanmalıdır. Security gereksinimleri eski platformların desteğini sonlandırmayı zorunlu kılabilir. Böyle durumlarda API sunset ile uygulama EOL iletişimi birlikte planlanmalıdır.

Uzun Kuyruklu Client Version Dağılımı

Mobile kullanıcı tabanında birkaç yeni version yoğun trafik üretirken çok sayıda eski sürüm küçük oranlarda yaşamaya devam edebilir. Bu uzun kuyruk migration kararını zorlaştırır. Yalnızca trafik yüzdesine bakmak kritik ama düşük trafikli kullanıcı grubunu gizleyebilir. Client count ve business impact de birlikte ölçülmelidir. Sunset readiness bu farklı metriklerin ortak değerlendirmesine dayanmalıdır.

Minimum Supported App Version

Minimum supported app version backend'in çok eski istemcileri engellemesini sağlayabilir. Bu mekanizma security veya ciddi compatibility sorunlarında gerekli olabilir. Ancak kullanıcıya yalnızca genel hata göstermek kötü deneyim oluşturur. Upgrade gereksinimi, mağaza bağlantısı ve neden bilgisi açıkça sunulmalıdır. Minimum version kararı telemetry ve product değerlendirmesiyle alınmalıdır.

Client Version'a Göre Response Üretmek

Backend bazen app version veya platform bilgisine göre farklı response davranışı üretmek zorunda kalabilir. Bu yaklaşım kısa vadede migration kolaylığı sağlar, fakat version check'ler business code içine dağılırsa bakım maliyeti hızla artar. Daha iyi yöntem client version'ı merkezi bir capability veya feature set'e çevirmektir. Business logic böylece “version 4.8'den büyük mü?” yerine “özellik X destekleniyor mu?” sorusuyla çalışır. Bu ayrım uzun ömürlü mobil ve multi-platform backend'lerde önemli ölçüde sadelik sağlar.

App Version Header

App version header backend'e istemcinin hangi uygulama sürümünü kullandığını bildirir. Bu bilgi telemetry, rollout ve compatibility kararlarında kullanılabilir. Header değeri güvenlik yetkilendirmesi yerine capability sinyali olarak değerlendirilmelidir. İstemci tarafından değiştirilebileceği unutulmamalıdır. Server mapping tablosu version değerini desteklenen feature set'e dönüştürebilir.

Platform

Platform bilgisi iOS, Android veya başka client ailesi için farklı capability'leri ayırt etmeye yardımcı olabilir. Aynı app version numarası platformlar arasında farklı release anlamına gelebilir. Bu nedenle version tek başına yeterli olmayabilir. Platform ve version birlikte mapping yapılabilir. Yine de business logic mümkün olduğunca bu teknik ayrıntılardan soyutlanmalıdır.

Capability Detection

Capability detection istemcinin hangi özellikleri desteklediğine odaklanır. Bu yaklaşım version numarasının dolaylı anlamını business code'a yaymayı önler. Server merkezi mapping veya istemci tarafından bildirilen güvenli capability set'i kullanabilir. Özellik kararları daha okunabilir hale gelir. Yeni client family eklendiğinde eski version karşılaştırmalarını tekrar yazmak gerekmez.

Response Shaping

Response shaping istemcinin capability set'ine göre belirli alanları veya representation'ı uyarlayabilir. Bu yöntem geçici migration dönemlerinde yararlı olabilir. Ancak çok sayıda koşullu response contract'ı test matrix'i büyütür. Farklı davranışların süresiz kalmasına izin verilmemelidir. Geçici compatibility kodunun removal tarihi ve owner'ı bulunmalıdır.

Version Check'lerin Kodda Dağılması Problemi

Business code içinde onlarca yerde app version karşılaştırması yapılması zamanla anlaşılması zor bir yapı oluşturur. Aynı version sınırı farklı dosyalarda farklı davranabilir. Yeni release geldiğinde mapping güncellemeleri kaçırılabilir. Merkezi capability resolver bu kontrolleri tek noktada toplar. Böylece test, cleanup ve feature flag entegrasyonu daha düzenli hale gelir.

Version → Feature Mapping Yaklaşımı

Version-to-feature mapping, teknik client version bilgisini iş kodunun anlayacağı capability set'ine dönüştürür. Bu model özellikle mobil backend ve farklı release ritmine sahip istemcilerde etkilidir. Mapping merkezi olduğunda version koşulları kod tabanına dağılmaz. Feature flag sistemiyle birlikte kullanıldığında rollout ve compatibility aynı kavramsal katmanda yönetilebilir. Bununla birlikte mapping tablosunun düzenli temizlenmesi ve gerçek client dağılımıyla senkron tutulması gerekir.

Client Version'ı Feature Set'e Çevirmek

Resolver katmanı platform ve version bilgisini belirli feature flag veya capability listesine dönüştürebilir. Örneğin uygulama 5.2 ve üzeriyse yeni pagination özelliğini destekliyor kabul edilebilir. Business code yalnızca capability değerini kontrol eder. Böylece version numarasının anlamı tek yerde tutulur. Testler her version aralığı için beklenen feature set'i doğrulayabilir.

Backend'in Feature Üzerinden Karar Vermesi

Backend'in feature üzerinden karar vermesi kod okunabilirliğini artırır. “Client 6.1'den büyük mü?” yerine “cursor pagination destekleniyor mu?” sorusu domain açısından daha anlaşılırdır. Version değişse bile feature semantics aynı kalabilir. Bu yaklaşım yeni platformların sisteme eklenmesini kolaylaştırır. Capability kaldırıldığında eski mapping ve compatibility kodu kontrollü biçimde temizlenebilir.

Version Matrix

Version matrix hangi platform ve app version'ın hangi capability'leri desteklediğini gösterir. Bu tablo hem test hem support ekibi için değerli bir referanstır. Mapping koduyla dokümantasyonun farklılaşmaması için mümkünse tek source of truth kullanılmalıdır. CI testleri matrix'i otomatik doğrulayabilir. Eski version satırları EOL sonrası temizlenebilir.

Feature Flag Entegrasyonu

Feature flag sistemi rollout kontrolünü capability mapping ile birleştirebilir. İstemci özelliği teknik olarak desteklese bile server rollout oranına göre özelliği açmayabilir. Bu ayrım compatibility ile product rollout kavramlarını birbirinden ayırır. Flag kapatıldığında eski contract davranışı korunabilir. Deney tamamlandığında geçici flag'in kaldırılması yaşam döngüsünün parçası olmalıdır.

Mapping Drift'i Önlemek

Mapping drift, client capability tablosunun gerçek uygulama davranışından uzaklaşmasıdır. Yanlış version sınırı bazı istemcilere desteklemediği response'u gönderebilir. Release pipeline mapping testleri bu riski azaltır. Mobile app release metadata'sı merkezi config ile senkron tutulabilir. Mapping değişikliklerinin code review ve test kapsamına alınması önemlidir.

Feature Flag API Versiyonlamasının Yerini Alabilir mi?

Feature flag güçlü bir rollout aracıdır, fakat API contract versioning'in tam yerine geçmez. Flag bir özelliğin kimlere veya ne zaman açılacağını kontrol ederken versioning uzun ömürlü sözleşme ayrımını yönetir. Breaking response schema değişikliğini yalnızca feature flag arkasında tutmak migration ve support politikasını ortadan kaldırmaz. Capability ve flag mekanizmaları versioning'i tamamlayabilir. İyi tasarım bu araçların her birini kendi sorumluluk alanında kullanır.

Rollout Control

Feature flag yeni davranışı küçük bir kullanıcı veya istemci grubuna açmayı sağlar. Canary rollout sırasında hata oranı ve latency izlenebilir. Sorun çıkarsa flag kapatılarak hızlı geri dönüş yapılabilir. Bu özellik deployment ile feature activation'ı ayırır. Ancak kalıcı contract değişikliği için version policy yine gereklidir.

API Contract

API contract istemcinin uzun süre güvenebileceği request ve response sözleşmesini ifade eder. Feature flag geçici rollout durumu olduğu için bu garantinin yerine geçmez. Bir flag aylarca açık ve kapalı client davranışı üretirse sözleşme belirsiz hale gelebilir. Kalıcı farklar açık version veya capability contract'a dönüştürülmelidir. Böylece istemci ne beklemesi gerektiğini bilir.

Client Capability

Client capability istemcinin belirli özelliği teknik olarak destekleyip desteklemediğini gösterir. Feature flag ise özelliğin aktif olup olmadığını belirleyebilir. İki kavram birbirinden farklıdır. Backend önce capability uygunluğunu, sonra rollout durumunu kontrol edebilir. Bu ayrım eski client'lara yanlış özellik göndermeyi engeller.

Deneyler

Feature flag A/B veya kademeli deneyler için uygundur. Aynı contract içinde farklı product davranışları kısa süreli test edilebilir. Deney sonuçlandıktan sonra davranışlardan biri kalıcı hale getirilmelidir. Geçici branch'lerin süresiz bırakılması test yükünü artırır. Contract etkileyen deneyler ayrıca compatibility review'dan geçirilmelidir.

Feature Flag Kaldırma Yaşam Döngüsü

Her feature flag'in owner, oluşturulma amacı ve cleanup tarihi bulunmalıdır. Rollout tamamlandıktan sonra eski branch kodu kaldırılmalıdır. Aksi durumda version check ve flag kombinasyonları hızla çoğalır. Test matrix gereksiz şekilde büyür. Flag cleanup API lifecycle automation'ın düzenli bir parçası haline getirilebilir.

OpenAPI Specification'ın Versioning'deki Rolü

OpenAPI Specification versioning sürecinde contract as code yaklaşımının temel araçlarından biridir. Request, response, parameter ve security tanımları machine-readable hale geldiği için değişiklikler otomatik karşılaştırılabilir. Versioned spec dosyaları SDK generation ve documentation için aynı kaynağı kullanabilir. Fakat yalnızca dosyanın bulunması yeterli değildir; runtime server ile spec'in senkron kalması gerekir. CI/CD içinde lint, diff ve contract testleri bu senkronizasyonu güçlendirir.

Contract as Code

Contract as code API sözleşmesini source control içinde yönetilebilir bir artefact haline getirir. Değişiklikler pull request üzerinden review edilebilir. Breaking rule set otomatik çalıştırılabilir. SDK ve documentation aynı commit'ten üretilebilir. Böylece sözleşme değişiklikleri görünür, izlenebilir ve geri alınabilir hale gelir.

OpenAPI 3.x

OpenAPI 3.x modern REST API sözleşmelerini tanımlamak için geniş bir yapı sunar. Request body, schema, security, callbacks ve response tanımları makine tarafından işlenebilir. Operation ve parameter deprecation bilgileri de spec içinde ifade edilebilir. Bu metadata SDK ve documentation süreçlerine aktarılabilir. Organizasyonun hangi minor OpenAPI sürümünü desteklediği tooling uyumluluğu açısından ayrıca belirlenmelidir.

Spec'in API ile Senkron Tutulması

Spec ile server davranışı farklılaştığında contract otomasyonu güvenilirliğini kaybeder. Dokümantasyon yanlış endpoint veya field gösterebilir. SDK yanlış modellerle üretilebilir. Runtime validation veya integration testleri drift'i erken yakalamaya yardımcı olur. CI/CD pipeline spec değişmeden server contract'ının değişmesini engelleyecek kontroller içerebilir.

Versioned OpenAPI Files

Her major API version için ayrı OpenAPI dosyası tutmak açık bir model sunar. V1 ve v2 farkları structural diff ile karşılaştırılabilir. SDK generation hangi spec'ten yapıldığını net biçimde bilir. Dezavantajı ortak tanımların kopyalanması olabilir. Shared component stratejisi veya generation pipeline bu tekrarları yönetebilir.

Tek Spec + Version Metadata

Tek spec içinde version metadata kullanmak bazı API'lerde dosya çoğalmasını azaltabilir. Ancak farklı contract'lar büyük ölçüde ayrışıyorsa tek dosya anlaşılması zor hale gelir. Tooling'in version-specific output üretebilmesi gerekir. Schema ve endpoint visibility kuralları açık olmalıdır. Seçim, API'nin değişim yapısı ve tooling kapasitesine göre yapılmalıdır.

OpenAPI'de Deprecation Nasıl Gösterilir?

OpenAPI içinde deprecation bilgisinin contract'a eklenmesi geliştirici araçlarının eski operasyonları görünür biçimde işaretlemesini sağlar. Operation ve parameter seviyesinde deprecation metadata'sı kullanılabilir. Bunun yanında migration açıklaması ve replacement bilgisi description alanında açıkça verilmelidir. SDK generator destekliyorsa deprecated method veya parameter için compiler warning oluşturabilir. Böylece deprecation yalnızca web dokümantasyonunda kalan bir not olmaktan çıkar ve geliştiricinin kullandığı araç zincirine taşınır.

deprecated: true

deprecated: true bir operasyon veya desteklenen nesne için kullanımın sonlandırılmasının planlandığını belirtmekte kullanılabilir. Bu işaret tek başına removal tarihini ifade etmez. Geliştiriciye neden deprecated olduğu ve hangi alternatifin kullanılması gerektiği ayrıca açıklanmalıdır. SDK generator bu metadata'yı language-specific warning'e dönüştürebilir. Spec diff süreçleri de yeni deprecation işaretlerini release note üretiminde kullanabilir.

Operation Deprecation

Bir endpoint operasyonu deprecated olduğunda aynı işlevi sunan replacement mümkünse hazır olmalıdır. Dokümantasyon eski operasyonu görünür tutmalı fakat yeni entegrasyonlar için önerilmediğini belirtmelidir. Usage telemetry hangi client'ların hâlâ çağrı yaptığını göstermelidir. Migration guide request ve response farklarını açıklamalıdır. Sunset tarihi ancak geçiş yolu kullanılabilir hale geldikten sonra duyurulmalıdır.

Parameter Deprecation

Parameter deprecation istemcinin artık belirli bir request alanını kullanmamasını hedefler. Server geçiş döneminde parametreyi kabul etmeye devam edebilir. Yeni parameter veya davranış önceden sunulmalıdır. SDK method signature içinde deprecated annotation geliştiriciye erken uyarı verebilir. Kullanım telemetry'si field seviyesinde mümkünse removal kararına destek sağlar.

Schema Property Deprecation

Schema property deprecation response veya model alanının gelecekte kaldırılacağını ifade edebilir. İstemci yeni property'ye geçmek için yeterli süre kazanmalıdır. Bir süre eski ve yeni alan paralel döndürülebilir. SDK modellerinde eski property warning ile korunabilir. Removal yeni major SDK ve gerektiğinde yeni API version ile birlikte planlanmalıdır.

Migration Açıklaması

Deprecation etiketi geliştiriciye ne yapması gerektiğini tek başına söylemez. Migration açıklaması replacement endpoint, yeni field, deadline ve örnek dönüşüm bilgisi içermelidir. Before ve after request örnekleri özellikle faydalıdır. Kısa açıklama doğrudan OpenAPI description içine eklenebilir. Daha kapsamlı rehber aynı URL üzerinden dokümantasyonda sunulabilir.

SDK'lara Deprecation Warning Aktarmak

OpenAPI metadata'sı SDK generator tarafından language-specific deprecation annotation'a dönüştürülebilir. IDE veya compiler geliştiriciye eski method kullanımını gösterir. Bu uyarı API çağrısı production'a çıkmadan önce fark edilebilir. Warning mesajı replacement method adını içermelidir. Böylece deprecation iletişimi yalnızca runtime loglarına bağlı kalmaz.

API Spec Drift Nedir?

API spec drift, OpenAPI dosyasında tanımlanan sözleşme ile çalışan server davranışının zaman içinde farklılaşmasıdır. Bu durum generated SDK, documentation ve automated diff süreçlerini güvenilmez hale getirir. Drift küçük bir field değişikliğinden authentication davranışına kadar farklı biçimlerde ortaya çıkabilir. En etkili yaklaşım spec'i release sürecinin zorunlu parçası haline getirmektir. Runtime validation ve CI/CD kontrolleri drift'i production'a ulaşmadan önce yakalamaya yardımcı olur.

Server ve OpenAPI Arasındaki Fark

Server farklı bir response döndürürken OpenAPI eski şemayı göstermeye devam edebilir. Bu durumda istemci geliştiricisi doğru olmayan dokümantasyona göre kod yazar. Generated SDK da yanlış model üretebilir. Integration testleri gerçek response'u schema ile doğrulayabilir. Drift bulunduğunda yalnızca spec değil, değişiklik sürecinin neden atlandığı da incelenmelidir.

SDK'nın Yanlış Spec'ten Üretilmesi

SDK generation yanlış branch veya eski OpenAPI dosyasını kullanırsa package API ile uyumsuz hale gelebilir. Bu sorun release pipeline içinde spec commit hash'i kaydedilerek azaltılabilir. SDK artefact metadata'sı hangi contract'tan üretildiğini gösterebilir. Compile ve integration testleri generated client'ı gerçek server'a karşı çalıştırmalıdır. Böylece yanlış source kullanımının production'a çıkması engellenebilir.

Documentation Drift

Documentation drift kullanıcıya API'nin gerçekte yapmadığı davranışı anlatır. Manuel yazılmış örnekler güncellenmeden kalabilir. Documentation mümkün olduğunca OpenAPI ve test edilmiş örneklerden üretilmelidir. Version picker her sürüm için doğru içerik göstermelidir. Release gate dokümantasyon güncellemesini API değişikliğinin zorunlu adımı haline getirebilir.

Runtime Validation

Runtime validation gerçek request ve response'ları contract'a göre doğrulayabilir. Her production request için ağır validation yapmak gerekli olmayabilir. Sampling veya staging ortamında doğrulama kullanılabilir. Drift metriği gözlemlenebilir hale geldiğinde ekip hızlı aksiyon alabilir. Hassas veriler loglanmadan schema uyumu kontrol edilmelidir.

CI/CD'de Drift Kontrolü

CI/CD pipeline server değişiklikleriyle spec değişikliklerini birlikte kontrol edebilir. Contract test, integration test ve OpenAPI diff release öncesinde çalıştırılabilir. Yeni endpoint kodu varsa spec'te bulunması zorunlu tutulabilir. Generated SDK compile testi de pipeline'a eklenebilir. Bu otomasyon spec drift riskini geliştirmenin erken aşamasına taşır.

Breaking Change Detection Nasıl Otomatikleştirilir?

Breaking change detection eski ve yeni API sözleşmelerini karşılaştıran otomatik bir kalite kapısı haline getirilebilir. OpenAPI dosyaları structural diff için uygun bir temel sağlar. Removed path, yeni required parameter veya type change gibi kurallar pipeline içinde tespit edilebilir. Fakat otomasyon davranışsal değişiklikleri tek başına yakalayamaz. En iyi model structural diff, consumer contract testleri ve human review'u birlikte kullanmaktır.

Old OpenAPI

Old OpenAPI son yayınlanan veya production'da desteklenen contract'ı temsil eder. Diff işlemi için güvenilir bir baseline olması gerekir. Rastgele eski commit seçmek yanlış sonuç üretebilir. Release artefact'ı olarak saklanan spec en güvenilir kaynaklardan biridir. Birden fazla aktif version varsa her desteklenen contract ayrı baseline olarak test edilebilir.

New OpenAPI

New OpenAPI release edilmek üzere olan değişiklikleri içerir. Pull request sırasında eski contract ile karşılaştırılabilir. Breaking rule bulunduğunda pipeline developer'a hangi path veya schema'nın değiştiğini göstermelidir. Gerekli durumlarda onay mekanizması uygulanabilir. Böylece breaking change farkındalığı release sonuna bırakılmaz.

Structural Diff

Structural diff iki OpenAPI dokümanı arasındaki yapısal farkları analiz eder. Path, operation, parameter, schema ve response değişiklikleri tespit edilebilir. Bu yöntem hızlı ve otomasyona uygundur. Ancak business rule veya sort order gibi davranışları bilmez. Sonuçlar risk sınıflandırmasıyla human review'a sunulmalıdır.

Breaking Rule Set

Breaking rule set hangi değişikliklerin organizasyon açısından kırıcı kabul edildiğini tanımlar. Removed response field, type change veya optional-to-required dönüşümü tipik kurallardır. Enum genişletmesi client davranışına göre warning veya breaking olarak sınıflandırılabilir. Kurallar versioning policy ile aynı tanımı kullanmalıdır. Zamanla production incident'larından öğrenilen yeni kurallar sete eklenebilir.

CI/CD Quality Gate

CI/CD quality gate breaking change bulunduğunda release'i durdurabilir. Developer değişikliği yeni major version altında yayınlayabilir veya compatibility planı ekleyebilir. Bazı organizasyonlar istisna için explicit approval isteyebilir. Gate yalnızca engellemek değil, neden kırılma görüldüğünü anlaşılır biçimde açıklamak zorundadır. İyi feedback developer'ın sorunu hızlı düzeltmesini sağlar.

Human Review

Human review otomatik diff'in yakalayamadığı semantic etkileri değerlendirir. Bir alanın description değişikliği bile business anlamını değiştirebilir. Authorization, rate limit ve error behavior gibi konular uzman değerlendirmesi gerektirir. API design review değişikliğin migration maliyetini de hesaba katmalıdır. Otomasyon insan değerlendirmesinin yerine değil, onu daha odaklı hale getirmek için kullanılmalıdır.

OpenAPI Diff Neleri Yakalamalıdır?

OpenAPI diff mekanizması istemcinin derlenmesini veya runtime davranışını etkileyebilecek temel contract değişikliklerini yakalamalıdır. Removed path, operation, parameter ve response field bunların başında gelir. Type değişiklikleri, required durumları ve enum farkları da ayrı kurallar olarak değerlendirilmelidir. Her değişiklik aynı risk seviyesinde olmayabilir, bu nedenle warning ve blocking kategorileri oluşturulabilir. Kurallar organizasyonun gerçek SDK ve client davranışlarıyla düzenli olarak güncellenmelidir.

Removed Path

Removed path mevcut istemcinin endpoint'e erişimini doğrudan engeller. Diff aracı bunu yüksek öncelikli breaking change olarak işaretlemelidir. Route deprecated olsa bile removal policy ve kullanım verisi kontrol edilmelidir. Pipeline gerekirse sunset approval kaydı isteyebilir. Böylece accidental endpoint deletion production'a ulaşmadan yakalanır.

Removed Operation

Aynı path üzerindeki GET veya POST operasyonunun kaldırılması da breaking change oluşturur. Path varlığını sürdürdüğü için basit URL kontrolü bunu fark etmeyebilir. OpenAPI diff operation method seviyesinde karşılaştırma yapmalıdır. Replacement operation bilgisi migration notes içine eklenmelidir. Usage analytics ilgili method trafiğini ayrı göstermelidir.

Removed Parameter

Removed parameter istemci request üretimini ve SDK signature'ını etkileyebilir. Server unknown parameter kabul etse bile generated SDK'dan field kaldırılması compile-time değişiklik oluşturabilir. Parameter'ın request semantiğindeki rolü ayrıca değerlendirilmelidir. Önce deprecation uygulanması daha güvenlidir. Diff aracı removal'ı açık warning veya breaking rule olarak sunmalıdır.

New Required Parameter

Yeni required parameter eski request'lerin validation'dan geçmemesine neden olur. Bu nedenle otomatik diff'in en net breaking kurallarından biridir. Yeni field ilk aşamada optional sunulabilir. Adoption yeterli olduğunda yeni contract sürümünde required hale getirilebilir. Pipeline doğrudan required addition gördüğünde developer'dan migration açıklaması isteyebilir.

Type Change

Type change serialization ve deserialization kodunu etkiler. String'den integer'a veya object'ten array'e geçiş açık risk oluşturur. Bazı genişletmeler teorik olarak uyumlu görünse de generated SDK davranışı test edilmelidir. Diff aracı eski ve yeni schema tiplerini açıkça göstermelidir. Gerekirse yeni field adı veya yeni version tercih edilmelidir.

Required/Optional Change

Optional request alanının required yapılması kırıcıdır. Response tarafında required bilgisinin değişmesi SDK model üretimini de etkileyebilir. Diff tool iki yönü ayrı kurallarla değerlendirmelidir. Nullable semantics de required durumundan bağımsız incelenmelidir. Hedef dil generator'larının davranışı compatibility testleriyle doğrulanmalıdır.

Enum Değişiklikleri

Enum value removal açık breaking change oluşturur. Yeni enum value eklemek ise forward-compatible olmayan client'larda sorun çıkarabilir. Bu nedenle additive enum change bile warning üretmelidir. SDK unknown fallback desteği varsa risk seviyesi düşebilir. Rule set gerçek client davranışına göre yapılandırılmalıdır.

Response Schema Değişiklikleri

Response schema değişiklikleri istemci parser ve model kodunu doğrudan etkiler. Field removal, type change veya envelope değişimi yüksek risk taşır. Yeni optional field da strict client'lar için test edilmelidir. Diff sonucu SDK preview build ile birleştirilebilir. Böylece değişikliğin developer-facing etkisi merge öncesinde görünür olur.

Structural Diff Tek Başına Yeterli midir?

Structural diff önemli bir koruma sağlar, fakat API contract'ın bütün davranışını temsil etmez. Business rule, authorization, sort order, rate limit ve hata kodları spec'te değişmeden farklılaşabilir. Bu nedenle yalnızca OpenAPI karşılaştırmasına güvenmek yanlış güven oluşturabilir. Consumer contract tests, golden client tests ve production traffic replay daha geniş compatibility sinyalleri sağlar. Human review da semantic değişikliklerin doğru sınıflandırılması için gerekli olmaya devam eder.

Behavioral Change

Behavioral change aynı schema altında farklı sonuç üretilmesini ifade eder. Örneğin filtre semantics veya default değer değişebilir. Structural diff bu farkı görmeyebilir. Gerçek kullanım senaryolarını içeren integration testleri davranış değişikliğini yakalayabilir. Release notes behavioral changes için ayrı kategori içermelidir.

Business Rule Change

Business rule değişikliği response şemasını değiştirmeden kabul veya reddetme kriterlerini etkileyebilir. Daha önce geçerli olan işlem artık reddedilebilir. İstemci bunu breaking change olarak deneyimler. Provider tests ve consumer-driven scenarios iş kurallarını contract seviyesine yaklaştırabilir. Kritik rule değişiklikleri migration ve iletişim planına dahil edilmelidir.

Error Code Change

HTTP status aynı kalsa bile machine-readable error code değişikliği istemci branch'lerini bozabilir. SDK exception mapping de farklı exception üretmeye başlayabilir. Error catalog contract'ın resmi parçası olmalıdır. Testler kritik error code'ları doğrulamalıdır. Yeni code eklenirken unknown error fallback davranışı da kontrol edilmelidir.

Sort Order Change

Sort order değişikliği response listesi aynı alanları taşısa bile istemci deneyimini değiştirebilir. Pagination ile birlikte kullanıldığında kayıt atlama veya tekrar görme gibi sorunlar oluşabilir. Default order contract içinde tanımlanıyorsa değişiklik açıkça değerlendirilmelidir. Belirsiz sıra yerine explicit sort parameter daha sağlamdır. Traffic replay eski ve yeni response sırasını karşılaştırabilir.

Rate Limit Change

Rate limit düşürmek schema'da görünmeyen operasyonel breaking change yaratabilir. İstemci aynı request hacminde daha fazla 429 almaya başlayabilir. Retry ve backoff davranışı sistem yükünü daha da etkileyebilir. Yeni limitler önce gözlemlenebilir ve gerekirse client cohort bazında uygulanabilir. Changelog ve developer communication bu değişikliği açıkça duyurmalıdır.

Authorization Change

Authorization rule değişikliği endpoint ve schema aynı kalırken access sonucunu değiştirebilir. Yeni scope zorunluluğu veya role kontrolü istemcinin 403 almasına neden olabilir. Güvenlik gerekçesi olsa bile migration etkisi izlenmelidir. Test ortamında yeni permission modeli önceden denenebilmelidir. Structured error response geliştiriciye hangi yetkinin eksik olduğunu anlatmalıdır.

Consumer-Driven Contract Testing Nedir?

Consumer-driven contract testing, API sağlayıcısının yalnızca kendi tasarımına değil gerçek tüketicilerin beklentilerine göre uyumluluğu doğrulamasını sağlar. Consumer hangi request'i gönderdiğini ve hangi minimum response davranışına ihtiyaç duyduğunu contract olarak ifade eder. Provider bu contract'ları her release öncesinde çalıştırır. Bu yöntem özellikle internal microservices ve kontrol edilen partner entegrasyonlarında güçlüdür. Structural OpenAPI diff ile birlikte kullanıldığında hem genel schema hem gerçek kullanım senaryoları korunabilir.

Consumer Contract

Consumer contract belirli bir istemcinin provider'dan hangi davranışı beklediğini tanımlar. Gereksiz tüm response alanlarını değil, gerçekten kullanılan beklentileri içermesi daha sağlıklıdır. Bu contract consumer repository'sinde veya merkezi broker yapısında tutulabilir. Provider değişikliği bu beklentilere karşı test edilir. Böylece client migration ihtiyacı release öncesinde görünür olur.

Provider Verification

Provider verification consumer contract'larını API server implementasyonuna karşı çalıştırır. Bir expectation artık karşılanmıyorsa pipeline hata verir. Bu kontrol breaking change'i production'a çıkmadan yakalar. Farklı consumer version'ları aynı provider release'e karşı test edilebilir. Sonuç deployment compatibility kararında kullanılabilir.

Pact

Pact consumer-driven contract testing yaklaşımını uygulamak için kullanılan açık kaynak araçlardan biridir. Consumer interaction'ları contract artefact'ına dönüştürülebilir. Provider bu beklentileri CI içinde doğrulayabilir. Araç kullanmak tek başına iyi contract tasarımı sağlamaz; expectation kapsamı doğru seçilmelidir. Gereksiz derecede implementation detail'e bağlanan contract'lar migration esnekliğini azaltabilir.

Pact Broker

Pact Broker benzeri merkezi contract deposu consumer ve provider version'ları arasındaki doğrulama sonuçlarını tutabilir. Bu yapı hangi consumer'ın hangi provider release ile uyumlu olduğunu görünür hale getirir. Deployment gate bu veriye göre karar verebilir. Contract ownership ve retention politikası ayrıca tanımlanmalıdır. Merkezi görünürlük büyük microservice ortamlarında dependency yönetimini kolaylaştırır.

Provider Version

Provider version her deployment candidate'ının contract verification sonucu ile ilişkilendirilmesini sağlar. Böylece hangi server build'inin hangi consumer expectations'ı karşıladığı görülebilir. Branch ve environment bilgisi bu metadata'ya eklenebilir. Release pipeline doğrulanmamış build'i production'a göndermeyebilir. Bu yaklaşım compatibility durumunu soyut bir test sonucundan deployment kararına dönüştürür.

Deployment Compatibility

Deployment compatibility yeni provider sürümünün mevcut consumer'larla güvenli biçimde çalışıp çalışamayacağını belirler. Yalnızca testlerin yeşil olması değil, production'da aktif consumer version'larının hangileri olduğu da önemlidir. Broker verisi ile usage inventory birleştirildiğinde karar daha güçlü olur. Eski ve artık kullanılmayan consumer contract'ları yanlış alarm üretmemelidir. Bu nedenle last-seen ve ownership bilgisi contract lifecycle'a bağlanmalıdır.

Contract Testing Ne Zaman Kullanılmalıdır?

Contract testing özellikle provider ile consumer'ın farklı release döngülerine sahip olduğu sistemlerde büyük değer sağlar. Internal microservices, frontend-backend, mobile-backend ve partner entegrasyonları bunun yaygın örnekleridir. Çok sayıda bağımsız public consumer bulunan API'lerde tüm istemciler contract yayınlamayabilir, fakat kritik müşteriler için yine kullanılabilir. Contract testleri end-to-end testlerin yerine geçmez. Ama breaking change riskini daha erken ve daha hızlı tespit eden tamamlayıcı bir güvenlik katmanı oluşturur.

Internal Microservices

Internal microservices farklı ekipler tarafından geliştirildiğinde contract testing koordinasyon maliyetini azaltır. Consumer beklentileri machine-readable hale gelir. Provider release'i bağımlı servislerin kritik kullanımını otomatik doğrulayabilir. Dependency mapping ile birlikte hangi consumer'ın aktif olduğu görülebilir. Bu yaklaşım her değişiklik için uzun manuel toplantı ihtiyacını azaltabilir.

Frontend–Backend

Frontend ve backend farklı release ritmine sahipse contract testleri API shape değişikliklerini erken yakalar. Frontend'in gerçekten kullandığı field ve error davranışı contract'a dahil edilebilir. Backend yeni response yayınlamadan önce bu beklentileri doğrular. Generated TypeScript client kullanılıyorsa compile tests de ek güvence sağlar. Böylece staging ortamına kadar beklemeden incompatibility görülebilir.

Mobile–Backend

Mobile client'larda eski uygulama sürümleri uzun süre production'da kaldığı için contract testing özellikle değerlidir. Desteklenen eski mobile versions için golden contract set tutulabilir. Yeni backend build bu contract'lara karşı test edilir. App version usage verisi hangi testlerin hâlâ gerekli olduğunu belirleyebilir. EOL sonrası eski contract testleri kontrollü biçimde kaldırılabilir.

Partner Integrations

Partner entegrasyonlarında contract testleri iki organizasyon arasındaki beklentiyi teknik olarak doğrulama imkanı verir. Sandbox testleriyle birlikte kullanıldığında migration güveni artar. Partner'ın tüm internal sistemini bilmek gerekmez. Yalnızca üzerinde anlaşılan request ve response davranışı test edilir. Contract değişikliği partner release takviminden önce fark edilebilir.

Kritik Third-Party Consumers

Public API'de tüm third-party client'lar contract yayınlamasa bile kritik müşteriler için özel test setleri tutulabilir. Gerçek kullanım örnekleri anonimleştirilmiş fixture olarak saklanabilir. Yeni server sürümü bu fixture'lara karşı doğrulanabilir. Böylece yüksek iş etkisine sahip consumer'lar daha güçlü koruma alır. Yine de genel backward compatibility politikası tüm kullanıcılar için korunmalıdır.

API Gateway ile Version Routing

API gateway version seçimini business service'in önünde merkezi biçimde yönetebilir. Path, header veya query değerine göre doğru backend veya adapter'a routing yapılabilir. Deprecated version'lar için ayrı rate limit, warning header ve logging politikası uygulanabilir. Bu merkezi katman migration telemetry'sini de kolaylaştırır. Ancak version logic'in tamamını gateway'e taşımak config yönetimini büyütebileceği için sorumluluk sınırı açık tutulmalıdır.

Path-Based Routing

Gateway /v1 ve /v2 prefix'lerine göre farklı upstream servisler seçebilir. Bu yöntem rollout ve rollback açısından oldukça görünürdür. V1 compatibility adapter ayrı deployment olarak çalıştırılabilir. Route metrics sürüm bazında otomatik ayrılır. Eski route sunset sonrasında gateway seviyesinde kapatılabilir.

Header-Based Routing

Header-based routing özel version header değerine göre upstream seçer. URL sabit kaldığı için client contract seçimi metadata üzerinden yapılır. Gateway header'ı log ve metric label olarak kaydedebilir. Cache katmanı version header'ı dikkate almalıdır. Unsupported value için merkezi ve yapılandırılmış hata dönmek developer experience'ı iyileştirir.

Gateway'de Default Version

Gateway request'te version yoksa belirli bir default kullanabilir. Fakat default'ın otomatik olarak en yeni version'a taşınması risklidir. Sabit default veya explicit version zorunluluğu daha öngörülebilirdir. Header göndermeyen client'lar ayrı metric ile izlenmelidir. Default policy değişikliği de normal migration sürecinden geçirilmelidir.

Deprecated Version Policy

Gateway deprecated version isteklerine ek response header veya warning ekleyebilir. Bu sayede business service koduna lifecycle logic dağıtılmaz. Request count ve last-seen client bilgisi merkezi olarak toplanabilir. Sunset yaklaştığında warning görünürlüğü artırılabilir. Route removal tek bir yönetim noktasından yapılabilir.

Per-Version Rate Limits

Her API version için farklı rate limit uygulanması bazı migration senaryolarında yararlı olabilir. Eski sürümün yeni trafik alması azaltılabilir veya yeni entegrasyonların yalnızca yeni version'a yönelmesi sağlanabilir. Ancak mevcut kritik client'ları cezalandıracak ani limit düşüşlerinden kaçınılmalıdır. Limit değişiklikleri de contract etkisi açısından değerlendirilmelidir. Usage dashboard version bazında 429 oranını göstermelidir.

Central Logging

Gateway central logging için version, client ID, endpoint ve SDK version gibi alanları standartlaştırabilir. Bu veri migration dashboard'un temelini oluşturur. Business servislerin her birinin farklı log formatı üretmesi gerekmez. Privacy ve retention politikaları baştan belirlenmelidir. Sunset readiness için gerekli metric'ler aynı merkezi veri setinden hesaplanabilir.

Version Adapter Pattern

Version Adapter Pattern eski ve yeni API contract'larını ortak internal model üzerinde çalıştırmayı amaçlar. V1 ve v2 request'leri adapter katmanında canonical modele çevrilir. Business logic tek yerde kalır ve response yeniden ilgili contract şekline dönüştürülür. Bu yaklaşım duplicate business code riskini azaltır. Bununla birlikte adapter'ların süresiz kalmaması için deprecation ve cleanup tarihi bulunmalıdır.

Canonical Internal Model

Canonical internal model business domain'in version bağımsız temsilidir. V1 ve v2 dış contract'ları bu modele map edilir. Böylece core service her API version ayrıntısını bilmek zorunda kalmaz. Modelin public contract ile birebir aynı olmaması esneklik sağlar. Adapter testleri dönüşümlerin veri kaybı oluşturmadığını doğrulamalıdır.

V1 Adapter

V1 adapter eski request formatını canonical modele dönüştürür. Response tarafında da internal sonucu v1 schema'ya çevirir. Deprecated logic bu katmanda izole tutulabilir. Usage azaldığında adapter tamamen kaldırılabilir. Business service böylece legacy koşullardan korunmuş olur.

V2 Adapter

V2 adapter yeni contract'ın request ve response dönüşümlerini yönetir. V2 domain modele daha yakın tasarlanmışsa adapter daha sade olabilir. Canary rollout sırasında v1 ve v2 adapter sonuçları karşılaştırılabilir. Mapping testleri her breaking field değişikliğini açıkça doğrulamalıdır. Yeni version zamanla canonical modelin evrilmesine de yol açabilir.

Request Transformation

Request transformation eski field adlarını, pagination formatını veya authentication metadata'sını internal modele çevirebilir. Dönüşüm açık ve deterministik olmalıdır. Gizli business rule'lar adapter içine taşınmamalıdır. Validation hangi katmanda yapılacağı net belirlenmelidir. Migration tamamlandığında eski transformation kodu kolayca silinebilmelidir.

Response Transformation

Response transformation canonical sonucu version-specific schema'ya dönüştürür. Eski client için gerekli legacy field'lar bu katmanda üretilebilir. Yeni v2 alanları yalnızca uygun contract'ta sunulur. Performance etkisi ölçülmelidir. Transformation hataları version-specific metrics ile takip edilmelidir.

Eski Versiyon Kodunu Business Logic'ten Ayırmak

Legacy version koşullarını business logic içine dağıtmak zamanla bakım maliyetini artırır. Adapter pattern bu ayrıntıları boundary katmanında toplar. Domain code daha temiz ve test edilebilir kalır. Eski version sunset olduğunda ilgili adapter kaldırılır. Bu yapı legacy cleanup işini çok daha görünür hale getirir.

Compatibility Layer Ne Zaman Mantıklıdır?

Compatibility layer, istemcileri hemen migrate etmenin çok pahalı veya riskli olduğu durumlarda eski contract'ı yeni sistem üzerinde yaşatabilir. Büyük customer base, legacy integration veya uzun ömürlü cihazlar buna örnektir. Translation layer request ve response farklarını gizleyebilir. Fakat bu katman bedelsiz değildir; test, monitoring ve performans maliyeti oluşturur. Bu nedenle compatibility layer kalıcı çözüm değil, açık sunset hedefi bulunan bir geçiş mekanizması olarak tasarlanmalıdır.

Legacy API

Legacy API'nin backend implementasyonu artık sürdürülebilir değilse compatibility adapter yeni platforma geçiş sağlayabilir. İstemciler eski contract'ı kullanmaya devam ederken internal sistem modernleştirilebilir. Bu yaklaşım migration riskini iki ayrı adıma böler. İlk adım backend değişimi, ikinci adım client migration olur. Legacy adapter'ın kullanım oranı sürekli izlenmelidir.

Büyük Customer Base

Binlerce bağımsız client'ın aynı anda migrate edilmesi gerçekçi olmayabilir. Compatibility layer uzun bir geçiş penceresi sağlar. Client cohort'ları aşamalı biçimde yeni contract'a alınabilir. Support ekipleri yüksek riskli müşterilere ayrı yardım sunabilir. Layer maliyeti customer migration değeriyle birlikte değerlendirilmelidir.

Çok Pahalı Client Migration

Bazı client'lar sertifikasyon, firmware veya kurumsal change process nedeniyle zor güncellenir. Bu durumda server-side translation daha düşük toplam maliyet oluşturabilir. Yine de security ve correctness sınırları korunmalıdır. Her legacy davranış sonsuza kadar emüle edilmemelidir. Ek maliyet ve risk düzenli olarak gözden geçirilmelidir.

Translation Layer

Translation layer eski request'i yeni domain modeline ve yeni response'u eski schema'ya dönüştürür. Mapping kuralları explicit testlerle korunmalıdır. Dönüşüm sırasında veri kaybı veya semantic farklar dokümante edilmelidir. Observability hangi request'in translated olduğunu göstermelidir. Bu katman kaldırılabilir biçimde bağımsız tutulmalıdır.

Operasyonel Maliyet

Compatibility layer ek deployment, log, test ve incident yüzeyi oluşturur. Performance latency de artabilir. Security patch'ler eski contract'a backport edilmek zorunda kalabilir. Bu maliyet migration dashboard ve support verileriyle görünür hale getirilmelidir. Sunset kararı yalnızca teknik borç değil, bu operasyonel maliyet üzerinden de değerlendirilebilir.

Deprecation Nedir?

Deprecation bir API operasyonu veya sürümünün artık yeni kullanım için önerilmediğini, fakat belirli süre çalışmaya devam edeceğini ifade eder. Removal ile aynı şey değildir. İyi deprecation süreci replacement hazır olduktan sonra başlar ve istemcilere geçiş için yeterli zaman verir. Runtime header, changelog, dashboard ve doğrudan iletişim birlikte kullanılabilir. Deprecation'ın amacı kullanıcıyı aniden kesmek değil, kontrollü sunset sürecini başlatmaktır.

Deprecation ile Removal Arasındaki Fark

Deprecation döneminde eski API hâlâ kullanılabilir. Removal sonrasında ise route veya davranış artık desteklenmez. Bu iki kavramın aynı anda uygulanması migration window'u ortadan kaldırır. İstemciye önce alternatif sunulmalı, sonra geçiş süresi verilmelidir. Support policy bu iki tarih arasındaki minimum süreyi tanımlayabilir.

Deprecation Tarihi

Deprecation tarihi eski contract'ın artık yeni entegrasyonlar için önerilmediği zamanı gösterir. Bu tarihten sonra developer portal yeni kullanıcıları replacement'a yönlendirmelidir. Mevcut client'lar ise çalışmaya devam edebilir. Usage monitoring bu andan itibaren migration KPI'larına dönüşür. Tarih changelog ve runtime metadata içinde görünür olmalıdır.

Yeni İstemcilerin Eski API'yi Kullanmamasını Sağlamak

Deprecated sürüm hâlâ çalışıyor diye yeni client'ların onu kullanmasına izin vermek migration yükünü artırır. Dokümantasyon default olarak current version göstermelidir. Yeni API key veya client registration belirli durumlarda eski version erişimini kısıtlayabilir. SDK'lar deprecated contract için yeni özellik üretmemelidir. Bu yaklaşım eski trafik havuzunun büyümesini engeller.

Mevcut İstemcilerin Çalışmaya Devam Etmesi

Deprecation döneminin temel amacı mevcut istemcilere migration zamanı vermektir. Server eski contract'ı tanımlanan support window boyunca çalıştırır. Critical security problemi oluşursa istisna politikası devreye girebilir. İstemciler runtime warning alırken iş akışına devam eder. Bu süre içinde migration owner ve deadline aktif olarak takip edilmelidir.

Deprecation HTTP Header

Deprecation HTTP header, API yaşam döngüsü bilgisini response içinde makine tarafından okunabilir biçimde taşımanın güçlü bir yoludur. Böylece istemci yalnızca dokümantasyon sayfasındaki duyuruya bağlı kalmaz. SDK, CLI veya monitoring sistemi response'u gözlemleyip warning üretebilir. Header kullanımı client ID ve usage telemetry ile birleştiğinde deprecation yönetimi daha otomatik hale gelir. Runtime sinyalinin migration guide ve support iletişiminin yerine geçmediği de unutulmamalıdır.

RFC 9745

RFC 9745, HTTP response içinde deprecation bilgisini iletmek için Deprecation header alanını tanımlar. Bu sinyal istemci araçlarının kaynağın deprecated durumunu programatik biçimde fark etmesine yardımcı olur. Header lifecycle bilgisini runtime response'a taşıdığı için yalnızca web dokümantasyonuna göre daha yakın bir bildirim noktasıdır. API gateway veya middleware bu değeri merkezi olarak ekleyebilir. Client SDK'lar da header'ı parse ederek geliştiriciye anlamlı uyarı gösterebilir.

Deprecation Date

Deprecation zamanı istemciye eski davranışın hangi noktadan itibaren deprecated kabul edildiğini gösterebilir. Bu tarih removal ile karıştırılmamalıdır. İstemci deprecation tarihinden sonra çalışmaya devam edebilir. Migration dashboard bu tarihten sonra eski version trafiğini aktif risk olarak işaretleyebilir. İletişim mesajlarında replacement ve sunset bilgisi de ayrı verilmelidir.

Machine-Readable Lifecycle Signal

Machine-readable lifecycle sinyali otomasyon sistemlerinin API durumunu insan müdahalesi olmadan algılamasını sağlar. SDK telemetry deprecated endpoint kullanımını merkezi metric'e çevirebilir. CLI doğrudan terminal warning gösterebilir. CI testleri deprecated operasyon çağrısını işaretleyebilir. Bu yaklaşım deprecation iletişimini yalnızca e-posta okunmasına bağlı olmaktan çıkarır.

Client SDK Tarafında Uyarı

SDK response header'ı algıladığında log veya warning üretebilir. Uyarı çok sık tekrar ederek uygulama loglarını doldurmamalıdır. Endpoint ve sunset bilgisi mümkünse tek, anlaşılır mesajda sunulmalıdır. Telemetry metriği geliştirici ekiplerinin kaç deprecated call yaptığını görmesini sağlayabilir. SDK warning policy major ve minor package release'lerden bağımsız çalışabilir.

Monitoring Entegrasyonu

Monitoring sistemi deprecation header dönen request'leri metric olarak sayabilir. Client ID, endpoint ve version label'ları migration dashboard'a aktarılabilir. Böylece yalnızca server total traffic değil, hangi consumer'ın risk taşıdığı görülür. Alert threshold sunset yaklaştıkça sıkılaştırılabilir. Bu veri support outreach önceliğini belirlemek için kullanılabilir.

Sunset Header Nedir?

Sunset header bir resource veya API davranışının gelecekte ne zaman erişilemez hale gelmesinin beklendiğini istemciye bildirir. Deprecation ile aynı anlamı taşımaz. Deprecation “artık kullanmamanızı öneriyoruz” mesajını verirken sunset “bu tarihten sonra erişim sona erebilir” bilgisini taşır. Migration guide bağlantısı ayrı bir Link header veya dokümantasyon mekanizmasıyla sunulabilir. Bu ayrım yaşam döngüsünün geliştirici açısından anlaşılır olmasını sağlar.

RFC 8594

RFC 8594, Sunset HTTP response header alanını tanımlar. Header bir resource'un gelecekte erişilemez hale gelmesinin beklendiği zamanı HTTP date biçiminde bildirir. Bu bilgi istemciler için lifecycle planlama sinyali sağlar. Sunset tarihi bir migration rehberi ve replacement bilgisiyle desteklenmelidir. Header tek başına kullanıcıya tüm geçiş sürecini açıklamaz.

Endpoint Ne Zaman Erişilemez Olacak?

Sunset tarihi istemciye eski endpoint'in ne zamana kadar desteklenmesinin planlandığını gösterir. Bu tarih client migration deadline oluşturmak için kullanılabilir. Kritik consumer'ların bu tarihten önce geçtiği telemetry ile doğrulanmalıdır. Tarih değişirse iletişim kanallarının tamamı güncellenmelidir. Son güne kadar trafik beklemek yerine migration ilerlemesi haftalık izlenmelidir.

Deprecation ile Sunset Arasındaki Fark

Deprecation kullanımın artık önerilmediğini ifade eder. Sunset ise erişimin gelecekte sona ermesi beklenen zamanı bildirir. İki sinyal arasında bir migration window bulunması sağlıklı yaklaşımdır. Replacement deprecation başladığında hazır olmalıdır. Bu ayrım kullanıcıya hem “geçişe başla” hem “bu tarihten önce bitir” mesajını verir.

Migration Bilgisi İçin Link Header

Runtime response migration dokümantasyonuna işaret eden bağlantı bilgisi de taşıyabilir. Böylece geliştirici warning gördüğünde doğrudan doğru rehbere ulaşabilir. Doküman version-specific olmalı ve eski ile yeni contract farklarını açıklamalıdır. Link'in uzun süre geçerli bir URL olması önemlidir. İstemci SDK warning mesajı bu bilgiyi geliştiriciye gösterebilir.

API Deprecation Timeline Nasıl Tasarlanmalı?

API deprecation timeline replacement'ın hazır olmasıyla başlamalı ve removal ile sona eren açık aşamalardan oluşmalıdır. Önce yeni contract production kalitesine ulaşmalı, ardından deprecation duyurusu ve migration guide yayınlanmalıdır. Runtime header ve client notification aynı dönemde devreye alınabilir. Migration window boyunca usage client bazında izlenmeli ve kalan kritik consumer'lara doğrudan ulaşılmalıdır. Sunset tarihi yaklaşırken readiness gate uygulanmalı, şartlar karşılanıyorsa eski route kontrollü biçimde kaldırılmalıdır.

Replacement Hazır

Eski API deprecated ilan edilmeden önce kullanıcıların geçebileceği replacement hazır olmalıdır. Yeni endpoint veya version production kullanımına uygun olmalıdır. SDK ve dokümantasyon da aynı anda erişilebilir hale getirilmelidir. Aksi durumda istemciye çözümü olmayan bir warning verilmiş olur. Replacement stability migration güveninin temelidir.

Deprecation Duyurusu

Deprecation duyurusu değişikliğin nedenini, alternatifini ve planlanan timeline'ı açıklamalıdır. Yalnızca teknik detay değil, kullanıcı etkisi de belirtilmelidir. E-posta, changelog, developer dashboard ve runtime header birlikte kullanılabilir. Kritik partner'lara doğrudan contact üzerinden ulaşılmalıdır. Duyuru tarihi migration window'un başlangıcı olarak kaydedilebilir.

Migration Guide

Migration guide istemcinin eski contract'tan yenisine nasıl geçeceğini adım adım göstermelidir. Breaking changes listesi, endpoint mapping ve field mapping içermelidir. Before ve after örnekleri geliştiricinin farkı hızlı anlamasını sağlar. SDK upgrade komutları ve test checklist de eklenebilir. Deadline dokümanın üst kısmında açıkça görünmelidir.

Runtime Headers

Runtime headers deprecated API'yi gerçekten kullanan istemciye doğrudan sinyal verir. Böylece dokümantasyon duyurusunu görmeyen developer da uyarı alabilir. Gateway bu header'ları version bazında merkezi ekleyebilir. SDK warning ve telemetry mekanizmaları bu sinyali kullanabilir. Header değerlerinin staging ve production ortamlarında doğru çalıştığı test edilmelidir.

Client Notifications

Client notifications genel duyurudan daha hedefli iletişim sağlar. Inventory'deki owner ve contact bilgileri kullanılarak aktif v1 consumer'larına doğrudan mesaj gönderilebilir. Mesaj mevcut version, deadline ve migration linkini içermelidir. Kullanım sıfırlandığında client migration tamamlandı olarak işaretlenebilir. Bu yöntem destek ekibinin hangi kullanıcıya yeniden ulaşması gerektiğini görünür hale getirir.

Migration Window

Migration window deprecation ile sunset arasındaki gerçek geçiş süresidir. Süre client release cycle, business kritikliği ve destek politikası dikkate alınarak belirlenmelidir. Public ve mobile API'lerde internal servislere göre daha uzun süre gerekebilir. Window boyunca v1 ve v2 reliability korunmalıdır. Son haftalara kadar bekleyen client'lar için support kapasitesi ayrıca planlanmalıdır.

Sunset

Sunset tarihi eski contract'ın erişilebilirliğinin sona ermesinin planlandığı noktadır. Tarih önceden duyurulmalı ve runtime sinyalleriyle desteklenmelidir. Critical client trafiği kalıyorsa readiness gate sonucu yeniden değerlendirme yapılabilir. Güvenlik sorunu gibi istisnalar ayrı politika kapsamında ele alınmalıdır. Sunset kararının sürekli ertelenmesi de version proliferation maliyetini büyüteceği için disiplinli yönetilmelidir.

Removal

Removal eski route, adapter veya davranışın production'dan kaldırılmasıdır. Bu adım yalnızca traffic ve client readiness doğrulandıktan sonra uygulanmalıdır. Kapatılan endpoint yapılandırılmış 410 veya uygun hata cevabı döndürebilir. Migration documentation bir süre daha erişilebilir tutulmalıdır. Legacy code ve dashboard cleanup da removal işinin parçasıdır.

Bir API Version Ne Kadar Süre Desteklenmelidir?

Tek bir evrensel support süresi yoktur. Public API, mobile client, partner entegrasyonu ve internal microservice farklı release döngülerine sahiptir. En iyi yaklaşım istemci kitlesine göre açık ve önceden yayınlanmış bir support policy oluşturmaktır. Security backport maliyeti ve eski version operasyonel yükü de sürenin sürdürülebilir olmasını etkiler. Kullanıcı açısından en değerli özellik sürenin uzunluğundan çok öngörülebilir olmasıdır.

Public vs Internal API

Public API kullanıcılarının release kontrolü sağlayıcının dışında olduğu için genellikle daha uzun support süresi gerekir. Internal API consumer'ları doğrudan koordine edilebilir. Bu durum internal sistemlerde daha kısa migration window kullanılmasını mümkün kılabilir. Yine de kritik dependency sayısı yüksekse süre uzayabilir. Policy client ownership gerçekliğine göre belirlenmelidir.

Client Release Cycle

Support süresi en yavaş kritik client'ın release döngüsünü hesaba katmalıdır. Mobile app, embedded device ve enterprise integration farklı hızlarda değişir. Bir aylık release cycle bulunan sistemle yılda iki kez release yapan partner aynı timeline'a zorlanmamalıdır. Inventory bu farklılıkları göstermelidir. Sunset tarihleri gerçek deployment davranışına göre seçilmelidir.

Enterprise Change Management

Kurumsal istemciler değişiklik için güvenlik review, test, onay ve deployment penceresi kullanabilir. Küçük API değişikliği bile haftalar süren iç süreç başlatabilir. Support window bu gerçekliği görmezden gelirse müşteri kesintisi riski yükselir. Migration guide erken paylaşılmalıdır. Büyük müşteriler için preview veya sandbox erişimi değerli olabilir.

Security Backport Maliyeti

Her aktif eski API version security fix backport gerektirebilir. Version sayısı arttıkça patch ve regression test maliyeti büyür. Bu maliyet support policy belirlenirken hesaba katılmalıdır. Çok eski sürümlerin güvenli tutulması pratik olarak mümkün değilse daha kısa support gerekli olabilir. Security exception policy acil durumda normal timeline'ın nasıl değişeceğini açıklamalıdır.

Açık ve Öngörülebilir Support Policy

Kullanıcı ne kadar süre destek alacağını önceden biliyorsa migration planını kendi roadmap'ine ekleyebilir. Policy version release, deprecation notice ve minimum sunset window bilgilerini içermelidir. İstisna durumları da açıkça tanımlanmalıdır. Her sürümde farklı ve habersiz kararlar kullanıcı güvenini azaltır. Tutarlı politika teknik seçimin kendisi kadar değerlidir.

Deprecated API Kullanımı Nasıl Ölçülür?

Deprecated API'yi kapatmadan önce kimlerin hâlâ kullandığını güvenilir biçimde ölçmek gerekir. Version, client ID, endpoint, request count, last-seen ve error rate temel metric'lerdir. Sadece toplam trafik oranı yeterli değildir, çünkü düşük trafikli fakat kritik bir istemci kalmış olabilir. Dashboard client ve business impact seviyesinde filtreleme sunmalıdır. Ölçüm sunset kararını varsayımdan çıkarıp gözlemlenebilir bir yönetim sürecine dönüştürür.

Version Header

Version header hangi contract'ın kullanıldığını doğrudan gösterir. Gateway loglarında ayrı field olarak tutulması analiz kolaylığı sağlar. Header göndermeyen client'lar default version kategorisinde ayrıca izlenmelidir. Migration sırasında v1 ve v2 dağılımı zaman serisi olarak gösterilebilir. Bu metrik adoption trendini açık hale getirir.

Client ID

Client ID toplam trafiği gerçek consumer'lara ayırır. Aynı v1 request sayısı on bin küçük client veya tek büyük entegrasyondan gelebilir. Migration taktiği bu iki durumda farklıdır. Client ID owner bilgisiyle birleştirildiğinde outreach otomasyonu kurulabilir. Anonymous traffic ayrıca risk grubu olarak ele alınmalıdır.

Endpoint

Endpoint bazlı kullanım hangi legacy operasyonların hâlâ aktif olduğunu gösterir. Bazı client'lar v1 içinde yalnızca tek deprecated route kullanıyor olabilir. Bu durumda tüm migration yerine dar bir endpoint geçişi planlanabilir. High-risk endpoint'ler ayrı dashboard'da gösterilebilir. Removal aşaması route bazında da yapılabilir.

Request Count

Request count legacy version üzerindeki trafik hacmini gösterir. Trend zaman içinde düşüyorsa migration ilerliyor demektir. Fakat yüksek request count her zaman yüksek client sayısı anlamına gelmez. Bu nedenle client ID ile birlikte değerlendirilmelidir. Peak ve average değerler capacity planning açısından da yararlıdır.

Last Seen

Last seen client'ın deprecated version'ı son kullandığı zamanı gösterir. Belirli süre trafik görülmeyen istemci migrate olmuş veya devre dışı kalmış olabilir. Seyrek çalışan batch job'lar için yeterince uzun gözlem penceresi seçilmelidir. Last-seen zamanının support outreach kaydıyla birlikte tutulması faydalıdır. Sunset readiness için kritik göstergelerden biridir.

Error Rate

Error rate migration sırasında eski ve yeni version kalitesini karşılaştırmaya yardımcı olur. V2'ye geçen client'larda hata artışı varsa rollout yavaşlatılabilir. Deprecated version'daki security veya reliability problemi de görülebilir. Error metric endpoint ve client cohort bazında ayrılmalıdır. Yalnızca global ortalama önemli sinyalleri gizleyebilir.

Traffic Share

Traffic share toplam API trafiğinin ne kadarının eski version'da kaldığını gösterir. Yüzde zamanla düşmelidir. Ancak küçük yüzde tek başına sunset için yeterli kriter değildir. Kalan client'ların kritikliği ve son görülme durumu da incelenmelidir. Readiness gate birden fazla metriği birlikte değerlendirmelidir.

API Migration Dashboard

API migration dashboard deprecation sürecini ekiplerin günlük olarak takip edebileceği operasyonel görünüme dönüştürür. Active client, v1 ve v2 client sayısı, request volume, owner ve deadline aynı yerde görülebilir. Böylece migration yalnızca dokümantasyon yayınlayıp beklenen bir süreç olmaktan çıkar. Support ve engineering ekipleri kalan consumer'ları önceliklendirebilir. Dashboard ayrıca sunset readiness toplantılarında ortak veri kaynağı görevi görür.

Active Clients

Active clients belirli gözlem penceresinde API trafiği üreten consumer sayısını gösterir. Toplam kayıtlı client sayısından daha anlamlı olabilir. Active tanımı günlük, haftalık veya aylık kullanım ritmine göre belirlenmelidir. Client type segmentasyonu eklenebilir. Sunset için kalan aktif v1 consumer sayısı özellikle önemlidir.

V1 Client Sayısı

V1 client count migration'ın ne kadar iş kaldığını gösteren basit ama değerli bir metriktir. Tek başına trafik yüzdesinden farklı bir bakış sağlar. Çok düşük trafik üreten onlarca eski client görünür hale gelir. Owner bilgisi olan client'lar otomatik outreach listesine eklenebilir. Zaman serisi migration hızını ölçmeyi sağlar.

V2 Client Sayısı

V2 client count yeni contract adoption'ını gösterir. İlk pilotlardan genel kullanıma kadar büyüme izlenebilir. Yeni client'ların doğrudan v2 ile başlaması ayrı metric olarak tutulabilir. V2 error rate ve SDK version bilgisi adoption kalitesini değerlendirmeye yardımcı olur. Sayının artması tek başına yeterli değildir, kullanım sağlığının da iyi olması gerekir.

Request Volume

Request volume version'ların gerçek trafik yükünü gösterir. Yüksek hacimli client'lar migration önceliği açısından önemli olabilir. V2 rollout sonrası latency ve capacity etkisi de volume ile birlikte analiz edilir. Peak saatlerde v1 ve v2 oranları farklı olabilir. Dashboard günlük toplamın yanında trend ve percentile görünümleri sunabilir.

Son V1 İsteği

Son v1 request zamanı her client için migration doğrulaması sağlar. Client sahibi “geçtik” dese bile gerçek trafik eski version'ı kullanmaya devam ediyor olabilir. Bu değer deployment sonrası doğrulamada çok yararlıdır. Belirli süre v1 request görülmeyen client completed olarak işaretlenebilir. Batch veya disaster-recovery senaryoları için yeterli gözlem süresi bırakılmalıdır.

Migration Owner

Migration owner her consumer'ın geçişinden kimin sorumlu olduğunu gösterir. Sahipsiz client'lar ayrı risk olarak işaretlenmelidir. Owner hem technical team hem external contact olabilir. Dashboard iletişim kaydını ve son durumu gösterebilir. Bu basit alan migration'ın organizasyonel sorumluluğunu görünür hale getirir.

Deadline

Her client için deadline global sunset tarihinden önce ara hedef oluşturabilir. Kritik consumer'lara daha erken tarih verilebilir. Geciken migration'lar dashboard üzerinde görünür hale gelir. Support ekipleri deadline yaklaşan owner'lara proaktif ulaşabilir. Tarihler gerçek release cycle ile uyumlu belirlenmelidir.

Migration Status

Migration status örneğin planned, in progress, testing ve completed gibi aşamalarla izlenebilir. Status mümkün olduğunca telemetry ile doğrulanmalıdır. “Completed” işaretinin ardından v1 traffic devam ediyorsa dashboard uyarı üretmelidir. Manual notlar özel blocker'ları açıklamak için kullanılabilir. Bu görünürlük cross-team coordination'ı kolaylaştırır.

Hangi İstemciler Önce Migrate Edilmelidir?

Migration sırasını rastgele belirlemek yerine risk ve öğrenme değeri üzerinden önceliklendirmek daha sağlıklıdır. En yüksek trafik veya en kritik iş akışı ilk bakışta önemli görünse de doğrudan en büyük müşteriyi pilot yapmak gereksiz risk yaratabilir. Önce iyi iletişim kurulan ve temsil gücü yüksek pilot client seçmek genellikle daha verimli olur. Pilot başarılı olduktan sonra yüksek trafik ve yüksek business impact taşıyan consumer'lar taşınabilir. En eski SDK ve incident riski yüksek client'lar da ayrı öncelik almalıdır.

En Yüksek Trafik

Yüksek trafik client'lar yeni version'ın capacity ve performance davranışını görmek için önemlidir. Ancak rollout doğrudan yüzde yüz yapılmamalıdır. Canary veya traffic splitting ile kontrollü geçiş daha güvenlidir. Error rate ve latency yakından izlenmelidir. Başarılı migration toplam v1 traffic share'i hızlı biçimde düşürebilir.

En Kritik İş Akışı

Kritik business flow'lar migration başarısızlığında büyük etki yaratabilir. Bu nedenle erken test edilmeli fakat yeterli rollback planı olmadan taşınmamalıdır. Shadow veya parallel run riski azaltabilir. Contract ve end-to-end tests gerçek iş senaryolarını kapsamalıdır. Migration owner operasyon ekibiyle birlikte readiness değerlendirmesi yapmalıdır.

En Büyük Müşteriler

Büyük müşteriler yüksek kullanım veya ticari önem nedeniyle özel planlama gerektirebilir. Önceden teknik iletişim ve test ortamı sunmak geçişi kolaylaştırır. Her büyük müşteri aynı zamanda ilk pilot olmak zorunda değildir. Platform kararlılığı küçük pilotlarla doğrulandıktan sonra büyük migration daha güvenli olur. Support capacity bu dönemde artırılabilir.

En Eski SDK

Eski SDK kullanan client'lar forward compatibility ve security açısından daha yüksek risk taşıyabilir. API migration ile SDK upgrade aynı anda gerekebilir. Bu durum change scope'u büyüttüğü için erken tespit edilmelidir. Compatibility matrix uygun upgrade yolunu göstermelidir. Client'a doğrudan önerilen package version sunmak süreci kolaylaştırır.

En Yüksek Incident Riski

Geçmişte sık hata yaşayan veya kritik retry davranışı bulunan client'lar migration sırasında ekstra dikkat gerektirir. Önce staging veya replay testlerinde doğrulanabilir. Observability daha ayrıntılı açılabilir. Rollback kriterleri önceden tanımlanmalıdır. Bu client'ların geçişi başarılı olduğunda platform güveni önemli ölçüde artar.

Pilot Client

İyi pilot client gerçek production kullanımını temsil ederken iletişimi kolay olan bir consumer'dır. Çok özel veya çok basit client seçmek yanlış güven oluşturabilir. Pilot sırasında migration guide ve SDK deneyimi de test edilmiş olur. Geliştirici geri bildirimi dokümantasyona hızlıca yansıtılmalıdır. Sonraki cohort'lar bu öğrenimlerle daha hızlı taşınabilir.

API Migration Stratejileri

API migration tek bir yöntemle yapılmak zorunda değildir. Big-bang, parallel run, client-by-client, canary, cohort ve shadow traffic farklı risk profillerine sahip yaklaşımlardır. Çok sayıda istemci bulunan sistemlerde kademeli yöntemler genellikle daha fazla kontrol sağlar. Seçim side-effect riski, client ownership, observability ve rollback imkanlarına göre yapılmalıdır. Migration planı teknik rollout kadar iletişim ve support akışını da kapsamalıdır.

Big-Bang Migration

Big-bang migration tüm istemcilerin belirli anda yeni version'a geçmesini hedefler. Az sayıda ve tam kontrol edilen client varsa uygulanabilir. Ancak geniş public veya mobile API'de operasyonel risk yüksektir. Sorun çıkarsa aynı anda çok sayıda consumer etkilenir. Bu nedenle güçlü test ve rollback olmadan tercih edilmemelidir.

Parallel Run

Parallel run v1 ve v2'nin belirli süre birlikte production'da çalışmasını sağlar. İstemciler kendi takvimlerinde kademeli olarak migrate edilir. Usage dashboard her version'ın trafik durumunu gösterir. Support window maliyeti artar fakat risk önemli ölçüde azalır. Çoğu büyük migration için dengeli bir yöntemdir.

Client-by-Client Migration

Client-by-client yaklaşım her consumer'ı ayrı plan ve doğrulamayla taşır. Kritik partner veya enterprise entegrasyonlarında oldukça uygundur. Owner, deadline ve test sonucu dashboard'da tutulabilir. Süreç çok sayıda client olduğunda operasyonel olarak ağır olabilir. Otomatik telemetry ve notification bu yükü azaltır.

Canary Migration

Canary migration önce küçük bir client veya trafik grubunu v2'ye taşır. Error rate ve latency normal kalırsa rollout genişletilir. Sorun çıkarsa hızlı rollback yapılabilir. Client cohort seçimi temsil gücüne sahip olmalıdır. Canary yalnızca server deployment değil, contract migration için de etkili bir yöntemdir.

Cohort-Based Migration

Cohort yaklaşımı client'ları platform, müşteri grubu, trafik veya risk seviyesine göre kümeler. Her grup ayrı wave halinde migrate edilir. Öğrenimler sonraki cohort'a aktarılır. Support ekipleri aynı anda sınırlı sayıda client'a odaklanabilir. Dashboard cohort progress'i açık biçimde göstermelidir.

Shadow Traffic

Shadow traffic gerçek request'in bir kopyasını v2'ye göndererek yeni davranışı production benzeri veriyle test eder. Primary response hâlâ v1'den geldiği için kullanıcı etkisi sınırlıdır. Side-effect içeren işlemler için kopya request dikkatle sandbox veya read-only moda alınmalıdır. Response diff mismatch metric üretebilir. Bu yöntem rollout öncesinde gizli behavioral differences bulmak için çok değerlidir.

Parallel Run Nasıl Çalışır?

Parallel run sürecinde v1 ve v2 aynı anda erişilebilir tutulur. Yeni client'lar doğrudan v2 kullanabilirken mevcut consumer'lar migration planına göre geçiş yapar. Gateway ve observability iki version'ın trafik, error rate ve latency değerlerini ayrı izler. V1 kullanım oranı düşerken kalan client'lara hedefli destek verilir. Sunset kriterleri sağlandığında eski version kapatılır ve legacy kod temizlenir.

V1 ve V2'nin Birlikte Çalışması

İki version'ın paralel çalışması business logic duplicate edilmeden tasarlanmalıdır. Adapter veya shared service katmanı ortak davranışı koruyabilir. V1 security fix'leri migration boyunca devam etmelidir. Capacity planı iki route'un toplam yükünü hesaba katmalıdır. Version-specific SLO'lar rollout sağlığını ölçer.

İstemcilerin Kademeli Taşınması

İstemciler pilot, cohort veya owner planına göre sırayla v2'ye geçirilebilir. Her migration sonrası v1 last-seen ve v2 traffic doğrulanmalıdır. Sorun yaşayan client geçici olarak geri alınabilir. Bu esneklik big-bang riski azaltır. Support notları sonraki client'ların geçişini hızlandırır.

Version Usage Monitoring

Parallel run boyunca version usage trendi ana başarı metriğidir. V1 traffic share, active client count ve last-seen birlikte izlenmelidir. V2 error rate ve latency de adoption ile paralel değerlendirilmelidir. Dashboard beklenmeyen geri dönüşleri gösterebilir. Migration tamamlandı varsayımı telemetry ile doğrulanmalıdır.

Eski Sürümün Kapatılması

V1 kapatma kararı önceden belirlenmiş readiness kriterlerine dayanmalıdır. Kritik client kalmaması ve traffic'in kabul edilen eşik altına düşmesi önemlidir. Sunset iletişimi tamamlanmalıdır. Kapatma sonrasında structured error ve migration bilgisi sunulabilir. Legacy route, monitoring ve adapter cleanup sonraki teknik adımı oluşturur.

Shadow Traffic ile V2 Nasıl Test Edilir?

Shadow traffic v1'e gelen gerçek production request'lerin güvenli bir kopyasını v2 ortamına gönderir. Kullanıcıya dönen asıl response v1'den gelir, böylece v2 sonucu doğrudan deneyimi etkilemez. V1 ve v2 response'ları normalize edilerek semantic farklar ölçülebilir. Side-effect içeren POST veya ödeme benzeri işlemler doğrudan tekrar edilmemelidir. Uygun sanitization ve read-only mekanizmalarıyla shadow test, gerçek kullanım çeşitliliğini yakalamada güçlü bir araçtır.

Primary Request V1'e

Primary request normal production akışında v1 tarafından işlenir. Kullanıcı alıştığı contract response'unu almaya devam eder. Shadow mekanizması ana request latency'sini artırmamalıdır. Kopyalama işlemi asynchronous veya ayrı trafik katmanında yapılabilir. Böylece test failure kullanıcı request'ini etkilemez.

Kopya Request V2'ye

Request'in kopyası v2 handler veya staging environment'a gönderilebilir. Hassas veriler gerekli kurallara göre maskelenmelidir. Authentication context güvenli biçimde temsil edilmelidir. V2 response kullanıcıya gönderilmez. Sonuç comparison pipeline için kaydedilir.

Response Comparison

V1 ve v2 response'ları birebir string olarak karşılaştırmak çoğu zaman yanlış alarm üretir. Timestamp, identifier veya bilinçli schema farkları normalize edilmelidir. Business açıdan eşdeğer alanlar semantic comparator ile kontrol edilebilir. Mismatch türleri category bazında metric'e dönüştürülebilir. Yüksek riskli farklar release blocker olabilir.

Side-Effect İçeren Request'lerde Dikkat

POST, ödeme veya e-posta gönderimi gibi side-effect işlemleri shadow ortamda iki kez çalıştırmak tehlikelidir. V2 handler dry-run veya isolated dependency kullanmalıdır. Event publish ve external call'lar engellenebilir. Idempotency tek başına her yan etkiyi güvenli hale getirmez. Shadow tasarımı her endpoint'in side-effect profilini ayrı değerlendirmelidir.

Mismatch Metrics

Mismatch rate v1 ve v2 arasında beklenmeyen davranış farklarının oranını gösterir. Endpoint ve client segment bazında ayrım yapılmalıdır. Known intentional differences allowlist ile filtrelenebilir. Trend sıfıra yaklaştığında rollout confidence artar. Kritik mismatch örnekleri developer'a debug edilebilir payload bağlamıyla sunulmalıdır.

API Canary Rollout

API canary rollout yeni version veya davranışı önce küçük bir client veya trafik yüzdesine açar. Amaç geniş migration öncesinde production koşullarında error rate, latency ve business metric'leri doğrulamaktır. Pilot cohort açık biçimde tanımlanmalı ve rollback kriterleri önceden belirlenmelidir. Sağlık göstergeleri normal kaldıkça trafik kademeli olarak artırılabilir. Bu yaklaşım özellikle internal veya kontrol edilebilir client gruplarında düşük riskli migration sağlar.

Pilot Clients

Pilot client gerçek kullanım biçimlerini temsil etmelidir. Sadece test amaçlı çok basit consumer yanlış güven verebilir. Owner'ı erişilebilir bir client seçmek geri bildirim süresini kısaltır. Pilot migration guide ve SDK deneyimini de doğrular. Başarı kriterleri rollout öncesinde yazılmalıdır.

Traffic Percentage

Trafiğin küçük yüzdesini v2'ye yönlendirmek teknik sağlık sinyali sağlar. Yüzde artışı otomatik veya manuel gate'lerle yapılabilir. Client stickiness gerekiyorsa aynı client'ın tutarlı version'a gitmesi sağlanmalıdır. Rastgele request splitting stateful akışlarda sorun oluşturabilir. Metric'ler her cohort için ayrı izlenmelidir.

Error Rate

Canary error rate baseline v1 ile karşılaştırılmalıdır. Yalnızca toplam 5xx değil, business error ve validation farkları da izlenmelidir. Küçük trafik hacminde oranların gürültülü olabileceği dikkate alınmalıdır. Kritik hata belirli eşik üzerinde rollout'u durdurabilir. Error sample'ları hızlı root cause analizi için saklanmalıdır.

Latency

Yeni adapter veya schema dönüşümü latency'yi artırabilir. Canary sırasında p50 yanında p95 ve p99 gibi percentile değerler incelenmelidir. Endpoint bazlı farklar global ortalamada kaybolabilir. Performance regression migration öncesinde düzeltilmelidir. Eski ve yeni version aynı production yükünde karşılaştırılmalıdır.

Automatic Rollback

Automatic rollback önceden belirlenmiş sağlık eşiği bozulduğunda trafiği eski version'a yönlendirebilir. Bu mekanizma hızlı incident containment sağlar. Ancak yanlış alarmın sürekli flip-flop oluşturması engellenmelidir. Rollback state ve nedeni loglanmalıdır. Data migration geri alınamıyorsa yalnızca routing rollback'in yeterli olup olmadığı ayrıca değerlendirilmelidir.

Cohort Expansion

İlk pilot başarılı olduğunda rollout daha büyük client gruplarına genişletilebilir. Her wave sonrası gözlem süresi bırakılmalıdır. Farklı client türleri yeni edge case'ler ortaya çıkarabilir. Migration support kapasitesi cohort büyüklüğüyle uyumlu olmalıdır. Son aşamada v2 default hale getirilebilir.

API Migration Guide Nasıl Yazılmalıdır?

API migration guide geliştiricinin eski contract'tan yenisine minimum belirsizlikle geçmesini sağlamalıdır. Neden migration gerektiği, hangi değişikliklerin breaking olduğu ve deadline en başta anlatılmalıdır. Endpoint ve field mapping tabloları hızlı referans sağlar. Before ve after request örnekleri özellikle karmaşık dönüşümlerde değerlidir. SDK upgrade, test checklist ve destek kanalı eklenirse rehber yalnızca açıklama değil, uygulanabilir bir geçiş planına dönüşür.

Neden Migration Gerekli?

Rehber ilk olarak değişikliğin neden yapıldığını açıklamalıdır. Güvenlik, daha tutarlı model veya yeni ürün gereksinimi gibi gerekçe kısa ve anlaşılır olmalıdır. Kullanıcı yalnızca “v1 kapanıyor” mesajıyla bırakılmamalıdır. Yeni version'ın sağladığı avantaj da belirtilmelidir. Bu bağlam migration önceliğinin anlaşılmasını kolaylaştırır.

Breaking Changes Listesi

Tüm breaking changes tek bölümde açık biçimde listelenmelidir. Removed endpoint, renamed field ve status code farkları ayrı maddeler olarak gösterilebilir. Her değişiklik için eski ve yeni davranış açıklanmalıdır. Belirsiz “API güncellendi” ifadeleri geliştiriciye yardımcı olmaz. Liste OpenAPI diff sonucu ile senkron tutulabilir.

Before / After Örnekleri

Before ve after örnekleri migration'ın gerçek kod etkisini hızlı gösterir. Request URL, header ve JSON farkları yan yana verilebilir. SDK method değişikliği de kısa snippet ile açıklanabilir. Örnekler test edilmiş olmalıdır. Yanlış dokümantasyon migration sırasında gereksiz support talebi oluşturur.

Endpoint Mapping

Endpoint mapping eski route'un yeni karşılığını doğrudan gösterir. Removed route için replacement yoksa bu durum açıkça belirtilmelidir. HTTP method değişiklikleri ayrıca görünür olmalıdır. Partner entegrasyonlarında mapping tablosu review süresini kısaltır. Doküman version-specific tutulmalıdır.

Field Mapping

Field mapping renamed, split veya merged alanların dönüşümünü açıklar. Veri tipi değişikliği varsa conversion örneği verilmelidir. Required ve optional farkları ayrıca belirtilmelidir. Null semantics gibi küçük görünen ayrıntılar da client bug'larına yol açabilir. Mapping generated SDK modelleriyle doğrulanmalıdır.

SDK Upgrade

Migration guide önerilen SDK version'ı ve upgrade komutunu göstermelidir. Major SDK change varsa package migration notes bağlantısı sunulmalıdır. Minimum runtime requirement açıkça belirtilmelidir. Eski SDK'nın v2'yi destekleyip desteklemediği compatibility matrix'te görünmelidir. Kullanıcı gereksiz package denemeleri yapmak zorunda kalmamalıdır.

Testing Checklist

Testing checklist authentication, pagination, error handling, retries ve kritik business flows gibi alanları kapsamalıdır. Kullanıcı yalnızca başarılı GET request test etmekle yetinmemelidir. Sandbox veya staging endpoint varsa belirtilmelidir. Webhook ve async event değişiklikleri ayrı test edilmelidir. Checklist migration'ın production readiness seviyesini yükseltir.

Deadline

Deadline migration guide içinde kolay görülen bir yerde bulunmalıdır. Tarih belirsiz bırakılırsa ekipler geçişi sürekli erteleyebilir. Deprecation ve sunset tarihleri ayrı gösterilmelidir. Tarih değişirse changelog ve client notification aynı anda güncellenmelidir. Kritik müşteriler için özel anlaşmalar varsa merkezi sistemde izlenmelidir.

Changelog Nasıl Yönetilmelidir?

Changelog API evolution'ın tarihsel kaydını kullanıcıya açık ve düzenli biçimde sunar. Breaking, additive, bug fix, security ve deprecation değişikliklerini birbirinden ayırmak geliştiricinin etkiyi hızlı anlamasını sağlar. Release date ile effective date farklıysa ikisi de belirtilmelidir. Changelog yalnızca marketing notu değil, contract değişiklik kaydı olarak ele alınmalıdır. OpenAPI diff ve release pipeline ile otomatik taslak oluşturmak güncelliği korumayı kolaylaştırır.

Breaking Changes

Breaking changes changelog içinde en görünür kategorilerden biri olmalıdır. Hangi version'ın etkilendiği açıkça belirtilmelidir. Migration guide bağlantısı aynı kayıt içinde bulunmalıdır. Effective date ve sunset ilişkisi gösterilmelidir. Kullanıcı uzun release notu içinde kritik değişikliği aramak zorunda kalmamalıdır.

Additive Changes

Yeni endpoint, optional field veya capability additive change kategorisinde yayınlanabilir. İstemcinin aksiyon alması gerekip gerekmediği belirtilmelidir. Enum expansion gibi potansiyel compatibility riskleri özel notla açıklanabilir. SDK'nın yeni özelliği hangi version'da expose ettiği de yazılabilir. Böylece kullanıcı yeni imkanları kolayca takip eder.

Bug Fixes

Bug fix contract değiştirmese bile observable behavior farklılaşabilir. Özellikle kullanıcıların yanlış davranışa bağımlı olabileceği durumlar changelog'da açıkça anlatılmalıdır. Fix'in effective date'i belirtilmelidir. Security olmayan kritik düzeltmeler de görünür olmalıdır. Gerekirse compatibility riskine karşı geçici flag veya rollout planı kullanılabilir.

Security Changes

Security değişiklikleri gerekli gizlilik sınırları korunarak kullanıcı etkisini açıklamalıdır. Credential rotation veya scope değişikliği gerekiyorsa aksiyon maddeleri net olmalıdır. Acil breaking fix normal timeline'dan sapabilir. Böyle durumda exception policy ve contact kanalları devreye alınmalıdır. Changelog tek başına yeterli değilse doğrudan notification yapılmalıdır.

Deprecations

Her deprecation kaydı affected endpoint veya version'ı, replacement'ı ve timeline'ı içermelidir. Yeni kullanıcıların deprecated özelliği seçmemesi için documentation current version'a yönlendirilmelidir. Runtime deprecation header aynı dönem etkinleştirilebilir. Usage dashboard adoption durumunu takip eder. Sunset yaklaşırken changelog kaydı güncellenebilir.

Release Date

Release date değişikliğin platform tarafından yayınlandığı günü gösterir. Bu tarih kullanıcıya history sağlar. Ancak feature staged rollout ile daha sonra aktif olabilir. Bu nedenle effective date farklıysa ayrıca yazılmalıdır. Versioned changelog kayıtlarının sıralanması release date üzerinden yapılabilir.

Effective Date

Effective date davranışın kullanıcı üzerinde fiilen geçerli olduğu zamanı gösterir. Özellikle deprecation, rate limit veya policy değişikliklerinde release date'den farklı olabilir. Kullanıcı planlaması açısından bu ayrım önemlidir. Tarih ve timezone net olmalıdır. İletişim kanallarının tamamı aynı effective date bilgisini kullanmalıdır.

Documentation'da Version Picker

Version picker kullanıcıların current, previous ve deprecated API dokümantasyonları arasında açık biçimde geçiş yapmasını sağlar. Varsayılan olarak en yeni desteklenen sürümü göstermek yeni entegrasyonların eski contract'a başlamasını engeller. Bununla birlikte mevcut v1 kullanıcıları geçmiş dokümantasyona erişebilmelidir. Version-specific examples ve OpenAPI dosyaları aynı seçime bağlı olmalıdır. Deprecated sürüm görünür bir warning ve migration bağlantısıyla sunulmalıdır.

Current Version

Current version yeni entegrasyonlar için önerilen contract'tır. Dokümantasyon ana sayfası varsayılan olarak bu sürümü göstermelidir. SDK install örnekleri de current version ile uyumlu package sürümünü kullanmalıdır. Current kavramı latest deployment ile karıştırılmamalıdır. Kullanıcı açısından desteklenen ve önerilen contract anlamına gelmelidir.

Previous Version

Previous version hâlâ support window içinde olabilir. Mevcut kullanıcıların referans ve migration için dokümana erişmesi gerekir. Search engine veya internal search sonucu kullanıcının yanlışlıkla eski sayfaya gitmesi durumunda version etiketi belirgin olmalıdır. Replacement link kolayca bulunmalıdır. Support status ve sunset tarihi sayfanın üst kısmında gösterilebilir.

Deprecated Version

Deprecated version dokümantasyondan tamamen kaybolmamalıdır. Aktif eski client sahipleri migration sırasında referansa ihtiyaç duyar. Sayfa açık warning, sunset tarihi ve yeni version bağlantısı içermelidir. Yeni API key veya onboarding flow deprecated version'ı önermemelidir. Removal sonrasında doküman bir süre historical migration reference olarak tutulabilir.

Version-Specific Examples

Request ve response örnekleri seçilen version'a uygun olmalıdır. V2 sayfasında yanlışlıkla v1 field adı göstermek ciddi confusion oluşturur. Örnekler CI içinde gerçek server veya schema'ya karşı doğrulanabilir. SDK snippet'leri de aynı version context'ini kullanmalıdır. Documentation generation pipeline bu tutarlılığı otomatik sağlayabilir.

Version-Specific OpenAPI

Her version için doğru OpenAPI dosyasına erişim verilmelidir. SDK generator ve API explorer version picker ile aynı contract'ı kullanmalıdır. Eski spec artefact'ları immutable biçimde saklanabilir. Diff ve migration tooling bu dosyalardan yararlanır. Kullanıcının yanlış spec download etmesini önlemek için version etiketi açık olmalıdır.

Default Olarak En Yeni Sürümü Göstermek

Yeni ziyaretçiyi current version'a yönlendirmek yeni legacy adoption oluşmasını engeller. Fakat mevcut kullanıcıların bookmarked eski doküman URL'leri çalışmaya devam etmelidir. Deprecated sayfalarda redirect yerine warning tercih etmek bazen daha faydalıdır. Çünkü migration yapan geliştirici eski contract bilgisine ihtiyaç duyabilir. Default seçim ile historical erişim birlikte desteklenmelidir.

SDK'lar API Değişiklikleriyle Nasıl Senkron Tutulur?

SDK'ların API değişiklikleriyle senkron kalması için OpenAPI contract'ı generation pipeline'ın ana girdisi haline getirilebilir. Spec değiştiğinde TypeScript, Python, Java, Go, C# veya Ruby gibi hedef diller için client kodu otomatik üretilebilir. Generated diff merge öncesinde incelenmeli ve breaking SDK değişiklikleri açıkça görülmelidir. Test ve package release adımları contract değişikliğiyle aynı pipeline içinde çalışabilir. Bu yöntem manuel SDK drift riskini ciddi ölçüde azaltır.

OpenAPI → SDK Generation

OpenAPI'den SDK generation tekrar eden model ve client kodunu otomatik üretir. Aynı contract farklı diller için tutarlı şekilde kullanılabilir. Generator configuration source control içinde tutulmalıdır. Generated code doğrudan güvenilmek yerine compile ve integration testlerinden geçirilmelidir. Spec değişikliği SDK diff'ini de review sürecine taşımalıdır.

TypeScript

TypeScript SDK frontend ve Node.js istemcileri için güçlü type safety sağlayabilir. Response model değişiklikleri compile-time etkiler oluşturabilir. Unknown enum ve optional field handling generator configuration'da dikkatle seçilmelidir. Package Semantic Versioning ile yayınlanabilir. Browser ve server runtime testleri ayrı çalıştırılabilir.

Python

Python SDK dynamic dil rahatlığı sunarken runtime validation davranışı önem kazanır. Generated model kütüphanesinin unknown field ve enum handling yaklaşımı test edilmelidir. Minimum Python version EOL policy ile uyumlu tutulmalıdır. Package release notes API compatibility bilgisini içermelidir. Integration tests gerçek response örneklerini deserialize etmelidir.

Java

Java SDK typed model ve enterprise kullanım senaryolarında yaygındır. Enum expansion ve nullable field değişiklikleri compile veya runtime etkisi yaratabilir. Generated code'un kullanılan HTTP client ve runtime sürümü support matrix içinde belirtilmelidir. Major SDK change migration notes gerektirir. Eski SDK ile yeni server kombinasyonu golden tests içinde tutulabilir.

Go

Go SDK sade type sistemi ve statik binary dağıtımı nedeniyle backend entegrasyonlarında kullanılabilir. Struct alanları ve pointer semantics optional field davranışını etkiler. Unknown JSON field'lar çoğu durumda tolere edilebilir, ancak custom decoder ayarları kontrol edilmelidir. Module versioning SDK major sürümlerinde dikkate alınmalıdır. Generated code gofmt, compile ve integration testlerinden geçirilmelidir.

C#

C# SDK .NET ekosisteminde typed models ve async API deneyimi sunabilir. Nullable reference types contract değişikliklerini daha görünür hale getirir. Serializer unknown field ve enum davranışı compatibility testleriyle doğrulanmalıdır. Target framework support policy açıkça yayınlanmalıdır. Package deprecation eski runtime kullanıcılarına migration sinyali sağlayabilir.

Ruby

Ruby SDK dynamic kullanım rahatlığı sağlarken runtime response parsing davranışı önemlidir. Generated model strict validation yapıyorsa additive change'ler beklenmeyen risk oluşturabilir. Gem versioning Semantic Versioning ile yönetilebilir. Minimum Ruby runtime sürümü support matrix'te bulunmalıdır. Integration tests gerçek API contract'ına karşı çalıştırılmalıdır.

SDK'ları CI/CD ile Otomatik Üretme

SDK generation CI/CD sürecine bağlandığında OpenAPI değişikliği otomatik olarak client impact review başlatabilir. Pipeline önce spec'i doğrular, ardından hedef dillerde SDK üretir ve generated diff'i gösterir. Compile test, integration test ve version bump kontrolü sonrasında package publish yapılabilir. Release notes hem API hem SDK değişikliğini açıklar. Bu otomasyon contract ile dağıtılan client paketleri arasındaki drift'i önemli ölçüde azaltır.

OpenAPI Spec Change

SDK pipeline OpenAPI diff ile tetiklenebilir. Her değişiklik package release gerektirmeyebilir, ancak generated output incelenmelidir. Breaking contract varsa SDK major impact otomatik işaretlenebilir. Spec commit ID artefact metadata'sına eklenebilir. Böylece package'ın hangi contract'tan üretildiği izlenebilir.

SDK Generation

Generator aynı configuration ve template ile deterministik output üretmelidir. Manuel edit generated code içinde kaybolmamalıdır. Custom helper code ayrı katmanda tutulabilir. Tüm hedef diller aynı contract release'ten üretilebilir. Generation failure API release'i durduracak bir quality gate olabilir.

SDK Diff

Generated SDK diff developer-facing etkiyi çok hızlı gösterir. Method rename, required property veya enum değişikliği source code seviyesinde görünür olur. Pull request reviewer yalnızca OpenAPI YAML farkına bakmak zorunda kalmaz. Büyük diff beklenmeyen contract etkisini ortaya çıkarabilir. Preview artefact client ekiplerinin erken test yapmasına imkan verir.

Test

SDK testleri compile, unit, serialization ve integration seviyelerini kapsamalıdır. Eski ve yeni server fixture'ları compatibility için kullanılabilir. Error response ve retry davranışı da test edilmelidir. Sadece happy path request yeterli değildir. Test sonucu package publish için zorunlu gate olmalıdır.

Version Bump

Version bump generated diff ve SDK public interface etkisine göre belirlenmelidir. Bug fix PATCH, additive feature MINOR ve breaking SDK change MAJOR olabilir. API contract version'la aynı numarayı kullanmak zorunlu değildir. Otomasyon öneri üretebilir, fakat human review kritik değişikliklerde faydalıdır. Release notes version kararının nedenini açıklayabilir.

Package Publish

Package publish yalnızca test ve approval tamamlandıktan sonra yapılmalıdır. Pre-release veya preview channel early adopter testleri için kullanılabilir. Package metadata API compatibility bilgisini içerebilir. Eski package deprecation gerekiyorsa aynı release planına eklenebilir. Publish sonrası smoke test gerçek package repository'den kurulum yaparak doğrulama sağlayabilir.

Release Notes

SDK release notes method, model ve runtime değişikliklerini geliştirici diliyle açıklamalıdır. API contract etkisi varsa ilgili migration guide'a yönlendirmelidir. Breaking change'ler en üstte görünmelidir. Minimum runtime veya dependency değişikliği ayrıca belirtilmelidir. Kullanıcı upgrade kararını yalnızca version numarasına bakmadan anlayabilmelidir.

SDK Preview Build Nedir?

SDK preview build, OpenAPI değişikliği merge edilmeden önce gelecekte oluşacak client paketini üretip incelemeyi sağlar. Pull request'te generated method, model ve type farkları görünür hale gelir. Client ekipleri local veya pre-release package ile gerçek uygulamalarını test edebilir. Bu yöntem özellikle yeni required property veya method rename gibi breaking etkileri erken yakalar. Contract review böylece yalnızca server bakışından değil, developer'ın kullanacağı SDK yüzeyinden de yapılır.

Pull Request'te SDK Diff

Pull request içine generated SDK diff eklemek reviewer'a somut client impact gösterir. OpenAPI'deki küçük bir değişiklik yüzlerce generated line değiştirdiyse risk hemen fark edilir. Diff hedef dillerin her biri için ayrı üretilebilir. Noise azaltmak için deterministic generation gereklidir. Reviewer beklenmeyen public interface değişikliklerini merge öncesinde yakalayabilir.

Method Rename

Operation ID değişikliği generated SDK method adını değiştirebilir. Server endpoint aynı kalsa bile SDK kullanıcıları compile error yaşayabilir. Preview diff bu etkiyi açıkça gösterir. Gerekirse operation ID korunabilir veya deprecated alias sağlanabilir. Böylece gereksiz SDK breaking change engellenir.

Type Change

Schema type değişikliği SDK model property tipini doğrudan değiştirebilir. Dynamic API kullanıcıları fark etmese bile statik dillerde compile impact oluşur. Preview package gerçek client repository'sinde test edilebilir. Conversion gerekiyorsa migration note hazırlanmalıdır. Bu yöntem API diff kuralının pratik etkisini doğrular.

New Required Property

Yeni required property generated constructor veya request modelini değiştirebilir. Mevcut client code derlenmeyebilir. Preview build bu sorunu server release'inden çok önce ortaya çıkarır. Alan optional tasarlanabiliyorsa contract yeniden değerlendirilebilir. Gerçekten required ise yeni version ve migration planı hazırlanmalıdır.

Local Test Package

Preview SDK local package veya pre-release registry üzerinden client ekibine sunulabilir. Gerçek application compile ve integration testleri çalıştırılır. Bu test generated unit testlerden daha geniş kullanım örnekleri yakalar. Feedback contract merge edilmeden önce alınır. Pilot consumer'lar için güçlü bir erken doğrulama süreci oluşturur.

Merge Öncesi Client Impact Review

Client impact review API değişikliğinin downstream etkisini release sonrası değil, pull request aşamasında tartışmayı sağlar. SDK diff, OpenAPI diff ve consumer contract sonuçları birlikte incelenebilir. Breaking değişiklik varsa migration planı merge kriteri olabilir. Bu yaklaşım ekiplerin “önce server'ı çıkaralım, sonra client'a bakarız” hatasını önler. Contract governance geliştirmenin doğal parçasına dönüşür.

SDK Forward Compatibility

SDK forward compatibility, eski client package'ın yeni server response'larını mümkün olduğunca güvenle işleyebilmesini amaçlar. Unknown enum value, yeni response field, optional property ve union genişlemeleri bu tasarımın temel test alanlarıdır. Aşırı strict validation SDK'yı API'den daha kırılgan hale getirebilir. Buna karşılık request tarafında kontrollü validation geliştirici hatalarını erken yakalayabilir. İyi SDK tasarımı strictness ile evolution esnekliği arasında bilinçli denge kurar.

Unknown Enum Values

SDK bilinmeyen enum değeri geldiğinde tüm response'u reddetmemelidir. Fallback enum veya raw value koruma yaklaşımı kullanılabilir. Uygulama bilinmeyen değeri güvenli default davranışla ele alır. Telemetry yeni değeri görünür hale getirebilir. Böylece server enum setini genişletirken eski SDK'lar tamamen bozulmaz.

Unknown Response Fields

Yeni response field'lar eski SDK tarafından çoğu durumda görmezden gelinebilmelidir. Strict unknown-property rejection additive evolution'ı zorlaştırır. Generated deserializer ayarları bu nedenle dikkatle seçilmelidir. Golden test yeni field içeren response'u eski SDK'ya vererek davranışı doğrulayabilir. Bu test SDK release policy'nin kalıcı parçası olmalıdır.

Optional Fields

Optional field bulunmadığında SDK güvenli biçimde null veya absence durumu sunmalıdır. Yeni optional alan eski client'ı etkilememelidir. Required model generation gereksiz compile break yaratabilir. API schema ve SDK nullability semantics aynı anlamı taşımalıdır. Farklı hedef dillerde optional representation ayrı test edilmelidir.

Union Types

Union type yeni variant'larla genişlediğinde SDK'nın unknown case davranışı önem kazanır. Closed union generation future expansion'ı zorlaştırabilir. Discriminator unknown fallback destekliyorsa client daha dayanıklı olur. Her hedef dil bu yapıyı farklı temsil edebilir. Generator configuration ve test fixture'ları language-specific riskleri yakalamalıdır.

Lax vs Strict Validation

Lax validation response evolution için esneklik sağlar. Strict validation ise contract dışı server hatalarını erken tespit edebilir. İki yaklaşımın trade-off'u API türüne göre değerlendirilmelidir. Response tarafında unknown field toleransı genellikle daha güvenli olurken request builder daha strict olabilir. Policy hedef diller arasında tutarlı hale getirilmelidir.

SDK'nin API'den Daha Kırılgan Olmasını Önlemek

API additive change desteklerken SDK yeni field yüzünden bozuluyorsa client tooling contract'tan daha kırılgan demektir. Golden compatibility tests bu durumu erken yakalar. Eski SDK ile yeni server response'ları düzenli olarak test edilmelidir. Generator upgrade'leri de aynı matrix'te doğrulanmalıdır. Böylece SDK kullanıcılarına daha güvenilir upgrade deneyimi sunulur.

SDK Upgrade Deneyimi Nasıl İyileştirilir?

SDK upgrade deneyimi yalnızca yeni package yayınlamakla tamamlanmaz. Semantic version, migration notes, deprecated method ve replacement bilgisi geliştiricinin değişikliği anlamasını kolaylaştırır. Compiler warning mümkünse runtime warning'den daha erken geri bildirim sağlar. Major upgrade için before ve after kod örnekleri hazırlanmalıdır. İyi upgrade deneyimi API migration süresini doğrudan kısaltabilir.

Semantic Version

Semantic version kullanıcıya release'in risk seviyesini hızlı anlatır. Major değişiklik daha dikkatli migration beklenmesi gerektiğini gösterir. Minor release additive feature, patch ise bug fix beklentisi oluşturur. Bu sözleşmeye sadık kalmak kullanıcı güveni sağlar. API version ile package version ayrımı dokümantasyonda korunmalıdır.

Migration Notes

Migration notes major SDK değişikliklerini adım adım anlatmalıdır. Method rename, import path ve type change ayrı başlıklarda açıklanabilir. Sadece changelog satırı büyük migration için yeterli değildir. Otomatik codemod veya search pattern varsa belirtilmelidir. Known issues ve rollback yolu da yararlı olabilir.

Deprecated Methods

Eski method hemen kaldırılmak yerine bir süre deprecated olarak tutulabilir. IDE uyarısı kullanıcıya replacement'a geçmesi gerektiğini gösterir. Method davranışı support window boyunca çalışmaya devam eder. Yeni kullanıcıların documentation örneklerinde deprecated method gösterilmemelidir. Sonraki major release'te removal yapılabilir.

Replacement Method

Her deprecated method mümkünse açık bir replacement göstermelidir. Yeni method adı, parameter farkı ve örnek kullanım warning mesajında belirtilebilir. Bu yaklaşım geliştiricinin dokümantasyonda uzun arama yapmasını azaltır. Replacement aynı API contract ile çalışıyorsa migration daha kolay olur. Breaking server change varsa ilgili API guide'a yönlendirme yapılmalıdır.

Compiler Warnings

Compiler warning geliştiricinin deprecated API kullanımını geliştirme aşamasında görmesini sağlar. Runtime production'a çıkmadan migration işi fark edilir. Warning mesajı actionable olmalıdır. Çok fazla gereksiz warning önemli sinyalleri görünmez hale getirebilir. Deprecation policy bu nedenle kontrollü uygulanmalıdır.

Runtime Warnings

Dynamic diller veya doğrudan HTTP kullanımında runtime warning faydalı olabilir. SDK response header'dan deprecation bilgisini okuyabilir. Log mesajı endpoint, sunset ve migration bilgisi içerebilir. Warning her request'te tekrarlanmak yerine rate-limited olabilir. Telemetry ayrıca merkezi migration metric üretebilir.

Eski SDK'lar Ne Kadar Süre Desteklenmeli?

SDK support süresi API support policy, runtime ekosistemi ve security gereksinimleriyle birlikte belirlenmelidir. Çok eski SDK major sürümlerini sonsuza kadar desteklemek test matrix'i ve patch maliyetini büyütür. Supported SDK matrix hangi package version'ların aktif bakım aldığını açıkça göstermelidir. EOL tarihi önceden duyurulmalı ve upgrade yolu sunulmalıdır. Unsupported SDK telemetry ile tespit edilebiliyorsa doğrudan client outreach yapılabilir.

Supported SDK Matrix

Matrix her dil için aktif, maintenance ve EOL SDK major sürümlerini gösterebilir. Hangi API version'larla uyumlu oldukları da aynı tabloda yer almalıdır. Runtime minimum sürümü ayrıca belirtilmelidir. CI test coverage matrix'teki destek sözünü doğrulamalıdır. EOL satırları historical reference olarak tutulabilir.

Security Patches

Supported SDK sürümleri kritik security patch alabilmelidir. Çok eski dependency veya runtime bunu imkansız hale getiriyorsa EOL gerekebilir. Güvenlik düzeltmesi API contract'tan bağımsız package release oluşturabilir. Kullanıcıya upgrade urgency açıkça belirtilmelidir. Deprecated package manager warning bu iletişimi güçlendirebilir.

EOL

EOL SDK sürümünün artık normal support veya patch almayacağı tarihi tanımlar. Bu tarih sürpriz olmamalıdır. Kullanıcılara replacement major version ve migration notes sağlanmalıdır. API support window ile çelişen SDK EOL durumları açıkça açıklanmalıdır. Telemetry eski SDK kullanımını takip etmeye devam edebilir.

Minimum Runtime Versions

SDK yeni language runtime sürümlerine geçmek zorunda kalabilir. Minimum runtime yükseltmek bazı kullanıcılar için breaking SDK change oluşturur. Bu değişiklik major release veya açık support policy gerektirebilir. Runtime EOL takvimleri önceden izlenmelidir. Kullanıcıya yükseltme için yeterli süre verilmelidir.

Unsupported SDK Warning

SDK veya API gateway çok eski package version'ı tespit ettiğinde warning üretebilir. Mesaj güvenlik ve support riskini açıklamalıdır. Kullanıcı doğrudan önerilen yeni version'a yönlendirilmelidir. Kritik durumda dashboard alert veya e-posta da gönderilebilir. Warning istemcinin request'ini hemen engellemek zorunda değildir.

API Error Response'ları da Versionlanmalı mı?

Error response API contract'ın ayrılmaz bir parçasıdır ve versioning değerlendirmesine dahil edilmelidir. İstemciler error code, type, validation detail ve status code üzerinden otomatik karar verir. Sadece message metnini değiştirmek bile kötü tasarlanmış client'larda sorun çıkarabilir. Daha güçlü yaklaşım machine-readable error type ve stabil field yapısı sunmaktır. Error schema breaking biçimde değişecekse normal response kadar dikkatli migration yapılmalıdır.

Error Schema Bir Contract'tır

Error object field'ları SDK ve client parser tarafından kullanılır. Code, type, message ve details gibi alanların anlamı açık olmalıdır. Field removal veya type change breaking risk taşır. OpenAPI response schema error modellerini de tanımlamalıdır. Contract diff bu modelleri normal response gibi analiz etmelidir.

Error Code

Machine-readable error code istemcinin belirli hataya programatik tepki vermesini sağlar. Code değerinin anlamı zaman içinde stabil kalmalıdır. Aynı code'u farklı business durum için yeniden kullanmak behavioral breaking change yaratabilir. Yeni code eklenirken unknown fallback davranışı düşünülmelidir. SDK exception mapping bu catalog ile senkron tutulmalıdır.

Error Message

Error message insan tarafından okunabilir açıklama içindir. İstemci logic'inin message metnini parse etmesi önerilmemelidir. Lokalizasyon veya wording değişikliği aksi durumda breaking etki yaratır. Stable error code bu bağımlılığı ortadan kaldırır. Message değişiklikleri yine observability ve support açısından dikkatle yapılmalıdır.

Machine-Readable Error Type

Error type istemcinin hata kategorisini güvenilir biçimde ayırt etmesini sağlar. Validation, authentication veya quota gibi türler açıkça tanımlanabilir. Yeni type eklenirken client unknown case'i güvenle ele almalıdır. Type URI veya code formatı version policy içinde sabit tutulabilir. SDK typed exception üretirken bu değeri kullanabilir.

Field-Level Validation Errors

Field-level validation error hangi request alanının neden reddedildiğini gösterir. Array path, error code ve message gibi yapılandırılmış bilgiler geliştirici deneyimini iyileştirir. Schema değişikliği bu parser'ları etkileyebilir. Yeni validation rule eklemek behavioral breaking risk taşıyabilir. Migration guide required field değişikliklerinde bu error formatını örneklemelidir.

Client Error Parser Uyumluluğu

Eski client error parser yeni server hata objesini güvenle işleyebilmelidir. Unknown detail field'lar görmezden gelinebilmelidir. Yeni error code tüm parsing'i bozmamalıdır. Golden SDK tests error response fixture'larını da kapsamalıdır. Böylece başarı response'una verilen compatibility önemi hata akışında da korunur.

HTTP Status Code Değişiklikleri Breaking Change Olabilir mi?

HTTP status code değişiklikleri istemci kontrol akışını değiştirdiği için breaking change olabilir. Bir SDK belirli status code'u farklı exception'a map edebilir veya retry policy yalnızca bazı kodlarda devreye girebilir. Bu nedenle “body aynı kaldı” yaklaşımı yeterli değildir. 200, 201, 204, 403 ve 404 gibi farklar client behavior açısından ayrı anlam taşır. Status code değişiklikleri contract diff, release notes ve client tests kapsamına dahil edilmelidir.

200 → 201

200'den 201'e geçiş semantik olarak oluşturma işlemini daha doğru ifade edebilir. Fakat bazı istemciler yalnızca 200'ü success kabul eden zayıf kod yazmış olabilir. SDK genellikle 2xx sınıfını doğru yönetmelidir. Değişiklik öncesinde gerçek client davranışı test edilmelidir. Public API'de uzun süredir kullanılan status code'u yalnızca estetik nedenle değiştirmek gereksiz risk oluşturabilir.

200 → 204

204 response body bulunmamasını ifade ettiği için 200 ile önemli davranış farkı yaratabilir. Eski istemci JSON body parse etmeye çalışırsa hata verebilir. Bu nedenle body kaldırılmasıyla birlikte açık breaking change değerlendirmesi yapılmalıdır. Yeni endpoint veya version daha güvenli olabilir. SDK return type değişikliği de ayrıca planlanmalıdır.

404 → 403

404 ile 403 istemcinin kaynak yokluğu ve yetki problemi hakkında farklı karar vermesine neden olur. Security tasarımı bazı durumlarda bilgi sızıntısını azaltmak için 404 kullanabilir. Bu davranışı değiştirmek client error handling'i etkiler. SDK exception mapping farklı exception üretebilir. Authorization migration ve error contract birlikte incelenmelidir.

Retry Davranışına Etkisi

İstemciler status code'a göre retry yapabilir veya request'i kalıcı hata kabul edebilir. Bir kod değişikliği retry storm veya gereksiz failure oluşturabilir. Retry-After ve idempotency semantics bu yüzden contract'ın parçası olarak görülmelidir. SDK policy server değişiklikleriyle birlikte test edilmelidir. Load test yeni retry davranışının backend kapasitesini nasıl etkilediğini gösterebilir.

SDK Exception Mapping

SDK HTTP status'u language-specific exception türüne map edebilir. Status code değişince kullanıcı catch ettiği exception'ı artık alamayabilir. Bu durum API schema aynı kalırken SDK behavior'ı kırar. Compatibility tests error mapping'i doğrulamalıdır. Release notes yeni exception davranışını açıkça anlatmalıdır.

Pagination Değişiklikleri Nasıl Versionlanmalıdır?

Pagination contract'ı request parameter, response envelope, ordering ve cursor semantics'in birleşimidir. Offset'ten cursor pagination'a geçiş yalnızca parameter adını değiştirmekten daha geniş etki oluşturur. Client loop logic, caching ve SDK modelleri değişebilir. Bu nedenle eski ve yeni pagination belirli süre paralel desteklenebilir. Migration guide next cursor kullanımını ve ordering garantilerini örneklerle açıklamalıdır.

Offset Pagination

Offset pagination page veya offset değerleriyle kayıt aralığını seçer. Kullanımı basittir fakat büyük veri setlerinde performans ve veri kayması sorunları olabilir. İstemciler page number davranışına bağımlı hale gelir. Cursor modeline geçiş breaking change sayılabilir. Eski endpoint bir süre offset desteğini koruyabilir.

Cursor Pagination

Cursor pagination istemciye sonraki sayfayı temsil eden opaque bir token verir. Backend veri seti değişirken daha stabil traversal sağlayabilir. Cursor içeriği istemci tarafından parse edilmemelidir. Token formatı contract dışında internal implementation detail kalmalıdır. Yeni pagination version'ında expiration ve ordering semantics açıkça belgelenmelidir.

Response Envelope

Pagination response envelope kayıt listesiyle birlikte metadata taşır. data, next_cursor veya benzeri alanların isimleri client modelini etkiler. Envelope eklemek mevcut bare array response'u kırabilir. Yeni version veya paralel endpoint düşünülebilir. SDK return type migration notes içinde açıklanmalıdır.

Next Cursor

Next cursor bir sonraki sayfanın alınması için kullanılacak token'dır. Son sayfada null, absence veya boş string davranışı açık olmalıdır. İstemci token'ı değiştirmemeli ve tekrar kullanma semantics'i bilmelidir. Cursor version internal format değişse bile istemci contract'ı mümkün olduğunca stabil kalmalıdır. Expiration hatası structured error ile bildirilmelidir.

Page Size

Default ve maximum page size istemci performance davranışını etkileyebilir. Limitin aniden düşürülmesi daha fazla request gerektirebilir. Bu değişiklik rate limit ve latency ile birlikte değerlendirilmelidir. Yeni page size parameter optional olarak sunulabilir. Changelog default değişikliklerini de açıkça belirtmelidir.

Eski ve Yeni Pagination'ın Paralel Desteklenmesi

Migration döneminde offset ve cursor yöntemleri farklı version veya endpoint üzerinden birlikte çalışabilir. Client'lar kendi takvimlerinde yeni loop logic'e geçer. Usage telemetry hangi pagination modelinin kullanıldığını göstermelidir. Cursor adoption yeterli olduğunda eski yöntem deprecated edilir. Business logic mümkün olduğunca ortak query katmanını kullanmalıdır.

Authentication Değişiklikleri Nasıl Migrate Edilir?

Authentication migration API lifecycle'ın en hassas değişikliklerinden biridir. API key'den OAuth gibi farklı bir modele geçiş credential oluşturma, secret storage, token refresh ve scope yönetimini etkiler. En güvenli yaklaşım çoğu zaman eski ve yeni yöntemi belirli süre paralel desteklemektir. Client bazında yeni authentication kullanım oranı takip edilmelidir. Eski yöntem sunset edilirken credential rotation ve support süreci açık bir runbook ile yürütülmelidir.

API Key → OAuth

API key'den OAuth'a geçiş client'ın yalnızca header değerini değiştirmesinden daha geniş bir değişikliktir. Token acquisition, expiration ve scope kavramları eklenir. SDK yeni authentication flow'u kolaylaştırmalıdır. Test environment client'ların yeni credential sürecini önceden denemesine imkan vermelidir. Eski key'ler sunset tarihine kadar kontrollü biçimde çalışmaya devam edebilir.

Token Formatı

Token formatı client'ın onu opaque değer olarak kullanması durumunda değiştirilebilir. İstemcinin token içeriğini parse etmesi tavsiye edilmemelidir. Ancak gerçek kullanımda bu bağımlılık oluşmuşsa migration riski bulunur. Token length ve storage limitleri de client'ı etkileyebilir. Yeni format rollout öncesinde SDK ve gateway testleri yapılmalıdır.

Scope Değişiklikleri

Yeni scope zorunluluğu mevcut token'ların yeterli yetkiye sahip olmamasına yol açabilir. Client'ların reauthorization veya credential update yapması gerekebilir. Scope mapping ve minimum permission açıkça dokümante edilmelidir. Authorization error'ları hangi scope'un eksik olduğunu güvenli biçimde anlatmalıdır. Migration dashboard yeni scope kullanan client sayısını gösterebilir.

Parallel Authentication

Parallel authentication eski ve yeni credential yöntemini aynı anda kabul eder. Bu model client-by-client migration için güçlü esneklik sağlar. İki yöntemin aynı authorization semantics'e sahip olduğu test edilmelidir. Eski yöntem üzerinde yeni client oluşturma sınırlanabilir. Usage azaldığında sunset adımı başlatılır.

Credential Rotation

Credential rotation migration sırasında eski secret'tan yeni token veya key'e geçişi kontrollü yapar. Bir süre iki credential'ın birlikte geçerli olması downtime riskini azaltabilir. Rotation audit log ile izlenmelidir. Secret distribution güvenli kanallarla yapılmalıdır. Client completed işaretlenmeden önce yeni credential kullanımı telemetry ile doğrulanmalıdır.

Authentication Sunset

Eski authentication yöntemi sunset edilmeden önce active usage client bazında sıfıra yakın olmalıdır. Direct outreach kalan kritik consumer'lara yapılmalıdır. Kapatma sonrası error response yeni authentication dokümantasyonuna yönlendirmelidir. Security gerekçesiyle daha erken sunset gerekiyorsa exception policy uygulanabilir. Eski secret'lar removal sonrası güvenli biçimde revoke edilmelidir.

Rate Limit Değişiklikleri Client'ları Nasıl Etkiler?

Rate limit API contract'ın operasyonel davranışını belirleyen önemli bir faktördür. Request quota veya burst limit değiştiğinde istemciler daha sık 429 response alabilir. SDK retry policy bu durumu kötüleştirebilir veya doğru backoff ile yönetebilir. Rate-limit header ve Retry-After gibi sinyaller client davranışını yönlendirmelidir. Limit değişiklikleri özellikle public ve partner API'lerde önceden duyurulmalıdır.

Request Quota

Request quota belirli zaman aralığında izin verilen toplam çağrı sayısını tanımlar. Quota düşürülmesi mevcut client iş akışını yavaşlatabilir. Önce usage distribution analiz edilmelidir. Büyük client'lar için migration veya batching önerileri sunulabilir. Yeni quota effective date ile birlikte duyurulmalıdır.

Burst Limits

Burst limit kısa sürede yapılabilecek request sayısını sınırlar. Günlük quota aynı kalsa bile burst limit düşüşü batch job'ları etkileyebilir. İstemci concurrency ve queue davranışı gözden geçirilmelidir. SDK exponential backoff desteği sağlayabilir. Monitoring burst rejection oranını client bazında göstermelidir.

Rate-Limit Headers

Rate-limit header'lar istemciye kalan quota ve reset bilgisi sunabilir. Formatın stabil olması client otomasyonu açısından önemlidir. Header adları veya semantics değişecekse migration planı gerekir. SDK bu bilgiyi typed metadata olarak expose edebilir. Dokümantasyon örnek response'larda değerlerin anlamını açıklamalıdır.

429 Handling

HTTP 429 client'ın rate limit aştığını gösterir ve ayrı retry davranışı gerektirir. İstemci aynı request'i anında tekrar gönderirse load artabilir. Backoff ve Retry-After bilgisi kullanılmalıdır. SDK default retry policy güvenli limitler içermelidir. Error body de machine-readable quota code taşıyabilir.

Retry-After

Retry-After istemciye yeniden deneme için bekleme süresi hakkında yönlendirme sağlar. SDK bu değeri destekliyorsa sabit retry interval yerine server sinyaline uyabilir. Format parse hataları test edilmelidir. Header bulunmadığında güvenli backoff fallback kullanılabilir. Retry logic idempotency özellikleriyle birlikte değerlendirilmelidir.

SDK Retry Policy

SDK retry policy hangi status code'larda kaç kez ve hangi backoff ile yeniden deneme yapılacağını belirler. Bu davranış API contract'la uyumlu olmalıdır. POST request'leri körlemesine retry etmek duplicate işlem riski yaratabilir. Idempotency key desteği önemli bir tamamlayıcıdır. SDK major değişikliklerinde retry default'ları değiştirilirse kullanıcıya açıkça bildirilmelidir.

Retry Semantics Bir API Contract'ı mıdır?

Retry semantics istemcinin timeout ve geçici hata durumlarında nasıl davranacağını belirlediği için fiilen API contract'ın parçasıdır. HTTP method idempotency, POST işlemlerindeki tekrar riski ve idempotency key desteği açık biçimde tanımlanmalıdır. Timeout sonrası server işlemi tamamlamış olabilir ve istemci sonucu bilemeyebilir. Bu belirsizlik özellikle ödeme veya sipariş oluşturma gibi operasyonlarda önemlidir. SDK retry davranışı server semantics ile birlikte tasarlanmalıdır.

Idempotent HTTP Methods

GET, PUT veya DELETE gibi method'ların retry davranışı HTTP semantics çerçevesinde değerlendirilmelidir. Uygulama implementasyonu yine de yan etki açısından doğru tasarlanmalıdır. İstemci network failure sonrası aynı request'i tekrar gönderebilir. Server duplicate processing riskini sınırlamalıdır. Dokümantasyon hangi operasyonların güvenle retry edilebileceğini açıkça söylemelidir.

POST Retry

POST çoğu zaman yeni kaynak veya işlem oluşturduğu için otomatik retry risklidir. Timeout sonrası ilk request server tarafından tamamlanmış olabilir. İkinci request duplicate kayıt yaratabilir. Idempotency key bu riski azaltmak için kullanılabilir. SDK POST retry'ı yalnızca contract açıkça destekliyorsa otomatik yapmalıdır.

Idempotency Key

Idempotency key aynı logical operation'ın tekrar request edilmesi durumunda duplicate execution'ı engellemeye yardımcı olur. Server key'i belirli süre saklayabilir. Aynı key ile farklı payload gönderilmesi açık error üretmelidir. Expiration ve scope semantics dokümante edilmelidir. SDK key generation veya forwarding desteği sunabilir.

Timeout Sonrası Belirsiz Sonuç

Client timeout aldığında request'in server'a hiç ulaşmadığını varsaymamalıdır. İşlem tamamlanmış fakat response ağda kaybolmuş olabilir. Bu durum duplicate retry riskinin temel kaynağıdır. Status endpoint veya idempotency mekanizması sonucu yeniden öğrenme imkanı sağlayabilir. Migration sırasında retry semantics değişirse istemciler özellikle uyarılmalıdır.

SDK Retry Davranışı

SDK retry default'ları developer tarafından fark edilmeden production davranışını etkileyebilir. Version upgrade sonrası retry sayısını değiştirmek load ve duplicate riskini artırabilir. Policy release notes içinde açık olmalıdır. Server rate limit ve idempotency desteğiyle birlikte test edilmelidir. Golden client tests eski ve yeni SDK retry davranışını karşılaştırabilir.

Webhook Versioning

Webhook event'leri de API kadar uzun ömürlü contract oluşturur ve ayrıca versioning gerektirebilir. API request version'ı ile webhook event version'ının zorunlu olarak aynı olması gerekmez. Consumer webhook endpoint'ini güncellemek için farklı release takvimine sahip olabilir. Event schema additive evolution, new fields ve removed fields açısından ayrı değerlendirilmelidir. Per-endpoint webhook version veya event metadata yaklaşımı migration esnekliği sağlayabilir.

API Version ile Webhook Version Aynı Olmalı mı?

Webhook lifecycle çoğu zaman request-response API'den bağımsızdır. Bir client API v2 kullanırken hâlâ v1 event schema tüketebilir. Bu bağımsızlık migration'ı daha küçük adımlara bölebilir. Ancak hangi kombinasyonların desteklendiği açık matrix ile gösterilmelidir. Aynı numarayı paylaşmak yönetimi kolaylaştırıyorsa bile zorunlu bir kural olmamalıdır.

Event Schema

Event schema consumer'ın webhook payload'ını nasıl parse edeceğini belirler. Field removal ve type change breaking risk taşır. Yeni fields forward-compatible parser'lar tarafından tolere edilmelidir. Schema registry veya versioned documentation kullanılabilir. Event fixture'ları consumer tests için yayınlanabilir.

Event Type

Event type consumer routing logic'inin temelidir. Var olan type'ı yeniden adlandırmak veya semantics'ini değiştirmek breaking change olabilir. Yeni type additive biçimde eklenebilir. Consumer unknown event type'ı güvenli biçimde ignore edebilmelidir. SDK webhook helper'ları fallback davranışı sağlamalıdır.

New Fields

Webhook payload'a yeni field eklemek çoğu parser için güvenli olabilir. Strict validation kullanan consumer'lar yine sorun yaşayabilir. Dokümantasyon unknown field toleransını önermelidir. Schema examples yeni field'ı açıkça göstermelidir. Additive event değişiklikleri changelog içinde yayınlanmalıdır.

Removed Fields

Webhook field removal consumer processing code'unu bozabilir. Önce deprecation ve replacement field sunulmalıdır. Dual field dönemi consumer migration'ına zaman kazandırır. Usage doğrudan field seviyesinde ölçülemiyorsa consumer contract tests daha önemli hale gelir. Removal yeni webhook version ile yapılabilir.

Per-Endpoint Webhook Version

Her webhook subscription'ın hangi event version'ı alacağını seçebilmesi esneklik sağlar. Client API version'dan bağımsız migration yapabilir. Developer dashboard subscription version'ını gösterebilir. Yeni subscription default olarak current event version kullanmalıdır. Deprecated event version kullanım sayısı sunset readiness için izlenmelidir.

Webhook Migration Stratejisi

Webhook migration request API migration'dan daha hassas olabilir çünkü event delivery async ve side-effect üretir. Dual delivery, consumer acknowledgement ve delivery monitoring güvenli geçişin temel araçlarıdır. Bir süre v1 ve v2 event'leri paralel test edilebilir, ancak duplicate business action riski kontrol edilmelidir. Consumer yeni formatı başarıyla işlediğini doğruladıktan sonra subscription version değiştirilebilir. Eski event formatı yalnızca aktif consumer kalmadığında kapatılmalıdır.

Dual Delivery

Dual delivery aynı logical event'in iki version formatında gönderilmesini sağlayabilir. Consumer v2'yi shadow endpoint'te test edebilir. Production business action'ın iki kez çalışmaması için endpoint ayrımı önemlidir. Delivery ID iki event'in aynı kaynağa ait olduğunu gösterebilir. Bu yöntem migration test süresini kısaltabilir.

V1 ve V2 Event'leri

V1 ve v2 event schema farkları açıkça dokümante edilmelidir. Event type aynı kalıyorsa version metadata bulunmalıdır. Consumer parser hangi schema'yı beklediğini bilmelidir. Test fixture'ları iki formatı yan yana göstermelidir. Compatibility layer gerekiyorsa delivery service içinde uygulanabilir.

Consumer Acknowledgement

Consumer yeni event version'ını başarıyla işlediğini explicit olarak doğrulayabilir. Developer portal veya API üzerinden migration status güncellenebilir. Telemetry success response'ları da bu beyanı desteklemelidir. Acknowledgement sonrası v1 delivery belirli grace period sonunda kapatılabilir. Böylece yanlışlıkla event kaybı riski azaltılır.

Delivery Monitoring

Webhook delivery success rate migration sırasında version bazında izlenmelidir. Retry count, latency ve response status temel metric'lerdir. V2 error artışı rollout'u durdurabilir. Consumer endpoint bazında last successful delivery gösterilebilir. Support ekibi sorun yaşayan client'a proaktif ulaşabilir.

Eski Event Formatını Kapatma

V1 event sunset öncesinde active subscription sayısı sıfıra yakın olmalıdır. Kalan consumer'lara doğrudan notification yapılmalıdır. Kapatma sonrasında eski subscription oluşturulması engellenmelidir. Historical event replay gerekiyorsa hangi schema'nın kullanılacağı açık policy ile belirlenmelidir. Legacy event serializer removal sonrası codebase'den temizlenmelidir.

Version-Specific Observability

Version-specific observability v1 ve v2'nin sağlık durumunu ayrı ayrı görmeyi sağlar. Request count, error rate, latency, authentication failure ve client count aynı dashboard'da version label ile izlenebilir. SDK version da eklenirse sorun belirli client package'a kadar indirgenebilir. Migration sırasında global API ortalamaları önemli farklılıkları gizleyebilir. Bu nedenle version dimension üretim telemetrisinin standart alanlarından biri olmalıdır.

Request Count

Request count version adoption trendini gösterir. V1 düşerken v2'nin artması beklenen migration desenidir. Endpoint bazında dağılım migration'ın hangi alanlarda yavaş olduğunu gösterebilir. Peak traffic ayrı incelenmelidir. Client ID ile birleştirildiğinde yüksek hacimli consumer'lar hızlıca bulunabilir.

Error Rate

Error rate yeni version'ın eskiye göre daha fazla problem üretip üretmediğini gösterir. HTTP errors yanında business validation errors da ayrı metric olabilir. Cohort bazında analiz pilot sorunlarını görünür hale getirir. Baseline v1 ile karşılaştırma yapılmalıdır. Belirlenen threshold rollout gate olarak kullanılabilir.

Latency

Latency yeni adapter veya backend path'in performance etkisini gösterir. Average değer tek başına yeterli değildir. Tail latency yüksek trafik client'larını etkileyebilir. Endpoint ve version kırılımı kullanmak root cause analizini kolaylaştırır. SLO'lar version bazında tanımlanabilir.

Rate-Limit Errors

429 oranı yeni version client'larının farklı request pattern üretip üretmediğini gösterir. Yeni SDK gereksiz retry yapıyorsa rate-limit errors artabilir. Client cohort ve SDK version kırılımı sorunun kaynağını bulmaya yardımcı olur. Limit policy version bazında farklıysa dashboard bunu açıkça göstermelidir. Migration sırasında beklenmeyen quota baskısı erken tespit edilebilir.

Authentication Failures

401 ve 403 artışı authentication migration sorununun işareti olabilir. Yeni token formatı veya scope eksikliği client'ları etkileyebilir. Error code category metric'e eklenmelidir. Client ID ve SDK version ile correlation yapılabilir. Support ekibi yaygın configuration hatasını hızlıca belirleyebilir.

Client Count

Client count traffic volume'dan bağımsız olarak kaç consumer'ın version kullandığını gösterir. Düşük trafikli ama aktif legacy client'ları görünür hale getirir. Daily ve monthly active tanımları kullanım modeline göre seçilebilir. Migration dashboard v1 active count trendini ana KPI olarak gösterebilir. Sunset readiness bu sayı üzerinden kural tanımlayabilir.

SDK Version

SDK version telemetry aynı API contract üzerinde farklı client package davranışlarını karşılaştırmayı sağlar. Belirli release'te error spike varsa hızlıca fark edilir. Unsupported SDK kullanımı da görünür hale gelir. Package migration campaign bu veriye göre hedeflenebilir. Privacy açısından yalnızca uygulama teknik metadata'sı tutulmalıdır.

API Version SLO'ları

Her aktif API version için availability, error rate ve latency hedefleri tanımlamak lifecycle yönetimini daha objektif hale getirir. Deprecated version artık yeni geliştirme almıyor olsa bile support window boyunca temel reliability beklentisini karşılamalıdır. Sunset yaklaşırken hizmeti bilinçli biçimde bozmak kullanıcı migration'ını zorlamak için doğru yöntem değildir. Aksine son güne kadar tanımlı SLO korunmalıdır. Böylece client'lar güvenli ve planlı biçimde yeni version'a geçebilir.

Availability

Availability her version'ın başarılı şekilde erişilebilir olma oranını gösterir. V1 deprecated diye reliability tamamen bırakılmamalıdır. Support policy minimum availability hedefini açıkça belirleyebilir. Büyük incident'lar migration schedule'ı etkileyebilir. Version-specific dashboard hangi contract'ın sorun yaşadığını hızla gösterir.

Error Rate

Error SLO client-visible failure oranını sınırlar. Yeni v2 rollout sırasında error budget hızlı tüketiliyorsa migration genişletilmemelidir. V1 ve v2 ayrı değerlendirilmelidir. Business error ile platform error ayrımı metric tanımında açıklanmalıdır. SLO breach release kararına bağlanabilir.

Latency

Latency SLO özellikle compatibility adapter kullanan version'larda önemlidir. Translation layer ek overhead oluşturabilir. p95 veya p99 hedefleri kritik endpoint'ler için ayrı belirlenebilir. Yeni version'ın daha yavaş olması kullanıcı adoption'ını olumsuz etkileyebilir. Performance optimization migration planının parçası olmalıdır.

Deprecation Döneminde SLO

Deprecation eski version'ın artık çalışmayacağı anlamına gelmez. İstemcilere belirli migration window verildiyse o süre boyunca hizmet güvenilir olmalıdır. Yalnızca yeni feature development durdurulabilir. Critical bug ve security fix support kapsamına göre devam eder. Bu yaklaşım kullanıcıya verilen lifecycle sözünü korur.

Sunset Öncesi Reliability

Sunset yaklaşırken eski version'ın bilerek yavaşlatılması veya kararsız bırakılması sağlıklı migration yöntemi değildir. Kullanıcı yeni contract'a kendi test planıyla geçebilmelidir. Reliability bozukluğu gerçek migration hatalarını ayırt etmeyi zorlaştırır. Son güne kadar tanımlı support seviyesi korunmalıdır. Sunset sonrasında ise route açık policy doğrultusunda kapatılabilir.

Sunset İçin Readiness Gate

Sunset kararı takvimdeki bir tarihi otomatik uygulamak yerine readiness gate ile doğrulanmalıdır. Eski trafik oranı, aktif client sayısı, kritik consumer durumu, support ticket'ları ve security riskleri birlikte incelenebilir. Product veya gerekli yönetim onayı da yüksek etkili public API'lerde sürece dahil edilebilir. Gate sürekli erteleme bahanesi olmamalı, önceden tanımlanmış objektif kriterlere dayanmalıdır. Bu yaklaşım hem plansız kesintiyi hem de sonsuz legacy support'u önlemeye yardımcı olur.

Eski Sürüm Trafik Oranı

V1 traffic share belirlenen eşik altına düşmüş olmalıdır. Ancak yüzde tek başına yeterli değildir. Kalan trafik kritik partner'a ait olabilir. Client count ve business impact birlikte değerlendirilmelidir. Trend son haftalarda stabil biçimde düşüyor mu ayrıca incelenebilir.

Aktif Client Sayısı

Aktif v1 client sayısı sunset riskini doğrudan gösterir. Çok düşük request volume olsa bile her client ayrı kesinti yaşayabilir. Kalan consumer'ların owner bilgisi bulunmalıdır. Unknown client varsa investigation yapılmalıdır. Sıfıra yakın veya kabul edilen istisna seviyesine gelmeden removal yapılmamalıdır.

Kritik Client Kaldı mı?

Business açısından kritik consumer hâlâ v1 kullanıyorsa sunset kararı dikkatle değerlendirilmelidir. Owner ile doğrudan migration planı oluşturulmalıdır. Blocker teknik mi organizasyonel mi netleştirilmelidir. Gerekirse kısa grace period uygulanabilir. Ancak istisnanın bitiş tarihi açık olmalıdır.

Migration Support Ticket'ları

Açık support ticket sayısı kullanıcıların hâlâ geçiş problemi yaşayıp yaşamadığını gösterir. Aynı hata çok sayıda client'ta görülüyorsa migration guide veya v2 bug'ı bulunabilir. Sunset öncesinde kritik blocker ticket'ları çözülmelidir. Ticket category trendi readiness toplantısına eklenebilir. Support feedback engineering kararına doğrudan girdi sağlar.

Security Riskleri

Eski version ciddi security riski taşıyorsa sunset hızlandırılması gerekebilir. Normal support policy bu durum için istisna kuralı içermelidir. Risk ile müşteri kesintisi dengeli biçimde değerlendirilmelidir. Gerekiyorsa emergency patch veya geçici compatibility yöntemi uygulanabilir. İletişim hızlı ve açık olmalıdır.

Executive/Product Approval

Yüksek etkili public veya enterprise API sunset kararı yalnızca teknik ekipten ibaret olmayabilir. Product, support ve ilgili yönetim paydaşları business impact'i değerlendirebilir. Approval süreci teknik kriterlerin yerine geçmemelidir. Dashboard ortak veri kaynağı sağlar. Karar ve istisnalar kayıt altına alınmalıdır.

Sunset Sonrası Ne Döndürülmeli?

Sunset sonrasında eski endpoint'e gelen request tamamen belirsiz bir 404 yerine migration'a yardımcı olacak yapılandırılmış cevap alabilir. 410 Gone uygun senaryolarda kaynağın bilinçli biçimde kaldırıldığını açıkça ifade eder. Error body replacement endpoint, migration documentation ve support contact bilgisi içerebilir. Geçici grace period uygulanacaksa davranışı açık ve sınırlı olmalıdır. Amaç legacy version'ı yeniden canlandırmak değil, kaçırılmış istemcinin sorunu hızlı anlamasını sağlamaktır.

410 Gone

410 Gone kaldırmanın bilinçli ve kalıcı olduğunu belirtmek için kullanılabilir. İstemci generic network error yerine lifecycle durumunu daha doğru anlayabilir. SDK bu status'u özel migration exception'a dönüştürebilir. Monitoring sunset sonrası kalan trafik miktarını izlemeye devam edebilir. Status choice API semantics'e göre dikkatle değerlendirilmelidir.

Structured Error

Structured error machine-readable code ve human-readable message içermelidir. Örneğin error type deprecated_version_removed gibi sabit bir anlam taşıyabilir. İstemci support ekranında doğru mesaj gösterebilir. Error schema mevcut API error contract'ıyla uyumlu olmalıdır. Migration URL'si ayrı field veya link metadata olarak sunulabilir.

Migration Documentation

Kapatılan route cevabında ilgili migration dokümanına yönlendirme yapılması support süresini azaltır. Doküman historical v1 bilgisini de korumalıdır. Kullanıcı neden request'in çalışmadığını ve nasıl düzelteceğini tek adımda anlayabilmelidir. Link uzun ömürlü olmalıdır. Removal sonrasında dokümantasyon hemen silinmemelidir.

Replacement Endpoint

Replacement endpoint varsa hata mesajında veya documentation içinde açıkça belirtilmelidir. Ancak otomatik redirect her HTTP method için güvenli olmayabilir. Özellikle POST body semantics farklıysa redirect yerine explicit migration önerilmelidir. SDK upgrade yeni endpoint'i otomatik kullanabilir. Client yine de contract farklarını test etmelidir.

Support Contact

Kritik enterprise veya partner client için support contact sunset sonrası son kurtarma kanalı olabilir. Contact bilgisi güncel ve doğru olmalıdır. Kullanıcı generic inbox içinde kaybolmamalıdır. Ticket metadata eski version ve client ID'yi otomatik ekleyebilir. Support ekibi aynı incident'ın yaygın olup olmadığını dashboard'dan görebilir.

Geçici Grace Period Gerekir mi?

Bazen beklenmeyen kritik client sunset sonrasında fark edilebilir. Kısa ve kontrollü grace period business kesintisini azaltabilir. Ancak bu yaklaşım sürekli deadline erteleme alışkanlığına dönüşmemelidir. İstisna client-specific veya sınırlı route erişimiyle uygulanabilir. Yeni bitiş tarihi ve migration owner açıkça belirlenmelidir.

API Version Proliferation Nasıl Önlenir?

Version proliferation her değişiklikte yeni major contract açılması ve eski sürümlerin kapatılamaması sonucu oluşur. Bu durum testing, security backport, documentation ve developer support maliyetini hızla büyütür. Additive evolution mümkün olduğunca aynı version içinde kullanılmalıdır. Maximum concurrent versions ve açık support window organizasyonun kaç legacy contract taşıyacağını sınırlar. Sunset politikası agresif olmak zorunda değildir, fakat gerçekten uygulanabilir ve öngörülebilir olmalıdır.

Her Değişiklikte Version Çıkarmamak

Yeni endpoint veya optional field için major version açmak çoğu zaman gerekli değildir. Önce değişikliğin gerçekten breaking olup olmadığı değerlendirilmelidir. Forward-compatible client tasarımı additive evolution alanını genişletir. Version yalnızca mevcut contract içinde güvenle çözülemeyen durumlarda kullanılmalıdır. Bu disiplin API yüzeyinin daha anlaşılır kalmasını sağlar.

Additive Evolution

Additive evolution mevcut contract'a geriye uyumlu özellik eklemeyi ifade eder. Optional fields ve yeni endpoints temel örneklerdir. Strict client davranışları yine test edilmelidir. Enum gibi riskli additive değişiklikler warning rule ile izlenebilir. Bu yaklaşım major version ömrünü uzatır.

Açık Support Window

Her sürümün ne kadar süre destekleneceği baştan bilinmelidir. Bu bilgi kullanıcı migration planını kolaylaştırır. Organizasyon da legacy maliyetini öngörebilir. Support window sonunda otomatik olarak removal değil, readiness review yapılabilir. Yine de sonsuz extension yerine açık istisna süreci kullanılmalıdır.

Maximum Concurrent Versions

Organizasyon aynı anda en fazla belirli sayıda major API version destekleme politikası belirleyebilir. Yeni version açılmadan önce en eski sürümün sunset planı hazırlanır. Bu kural version accumulation'ı sınırlar. Public API gerçekliği nedeniyle istisna gerekebilir. İstisna maliyeti ve bitiş tarihi kayıt altına alınmalıdır.

Aggressive Olmayan Ama Gerçek Sunset Policy

Sunset kullanıcıyı aceleye zorlayacak kadar kısa olmamalıdır. Fakat sürekli ertelenen deadline da policy'nin anlamını yok eder. Client release cycle'a uygun gerçekçi süre belirlenmelidir. Usage dashboard ve direct outreach geçişi destekler. Tarih geldiğinde readiness criteria sağlanıyorsa eski version gerçekten kaldırılmalıdır.

Eski API Sürümlerini Desteklemenin Maliyeti

Legacy API support yalnızca birkaç eski route'u açık tutmak anlamına gelmez. Her sürüm testing matrix, documentation, SDK, security backport, infrastructure ve support yükü oluşturur. Developer'lar business logic değiştirirken eski contract'ların etkisini düşünmek zorunda kalır. Bu cognitive load yeni feature hızını da etkileyebilir. Legacy maliyet görünür hale getirildiğinde sunset yatırımı teknik temizlikten ziyade ürün sürdürülebilirliği olarak değerlendirilebilir.

Testing Matrix

Her aktif API version test kombinasyonlarını çoğaltır. SDK version ve client type eklendiğinde matrix daha da büyür. Tüm kombinasyonları eşit düzeyde test etmek pratik olmayabilir. Supported matrix ve risk bazlı coverage uygulanmalıdır. EOL version kaldırıldığında test yükü de azaltılmalıdır.

Documentation

Her version için doğru endpoint, field ve example dokümantasyonu tutulmalıdır. Search sonuçlarında eski sayfanın yanlışlıkla öne çıkması kullanıcıları etkileyebilir. Version picker ve status banner bu riski azaltır. Dokümantasyon generation otomasyonu bakım maliyetini düşürür. Legacy version removal sonrası historical migration pages gerektiği kadar korunabilir.

SDK Support

Birden fazla API version SDK içinde adapter ve model çoğalmasına yol açabilir. Generated code büyür ve testing zorlaşır. Minimum supported API version zamanla yükseltilmelidir. Eski SDK major sürümlerinin EOL planı API lifecycle ile uyumlu olmalıdır. Compatibility matrix bu maliyeti görünür kılar.

Security Patch Backport

Security fix yalnızca current version'a uygulanırsa desteklenen legacy client'lar riskte kalabilir. Aynı patch eski code path'lere backport edilmek zorunda kalabilir. Legacy architecture farklıysa bu işlem pahalı hale gelir. Test ve release süresi uzar. Support policy belirlenirken security backport kapasitesi gerçekçi biçimde hesaba katılmalıdır.

Infrastructure

Eski version ayrı service veya deployment gerektiriyorsa compute ve operasyon maliyeti oluşur. Gateway routes, cache policies ve dashboards de büyür. Adapter aynı service içinde olsa bile CPU ve maintenance overhead yaratabilir. Capacity plan version traffic trendini dikkate almalıdır. Sunset sonrası kullanılmayan infrastructure hemen temizlenmelidir.

Developer Cognitive Load

Developer yeni feature geliştirirken v1, v2 ve v3 behavior farklarını hatırlamak zorunda kalabilir. Kod içine yayılmış version check'ler bu yükü artırır. Adapter ve canonical model yaklaşımı etkisini azaltır. Yine de her legacy contract domain anlayışını zorlaştırır. Version sayısını sınırlamak engineering velocity açısından değerlidir.

Support Maliyeti

Support ekibi her version'ın farklı davranışını bilmek zorunda kalabilir. Kullanıcı sorunu çözmek için önce API ve SDK version tespiti yapılır. Çok sayıda aktif contract ticket çözüm süresini uzatır. Migration dashboard ve version metadata bu teşhisi kolaylaştırır. Sunset sonrası support knowledge base sadeleşir.

Güvenlik Açığı Eski API Version'ında Bulunursa Ne Yapılmalı?

Eski fakat hâlâ desteklenen API version'ında security problemi bulunduğunda lifecycle policy güvenlik ihtiyacına göre esneyebilmelidir. Mümkünse patch backport yapılarak mevcut contract korunur. Backward-compatible fix mümkün değilse emergency deprecation veya breaking security change gerekebilir. Böyle durumda müşteri iletişimi normal release'ten daha hızlı ve daha doğrudan yürütülmelidir. Security exception kuralları önceden yazılmışsa kriz anında hangi ekiplerin hangi kararı vereceği daha nettir.

Patch Backport

Güvenlik fix'i eski contract behavior'ını bozmadan uygulanabiliyorsa backport en kullanıcı dostu seçenektir. Patch tüm desteklenen version'larda test edilmelidir. Legacy code farkları nedeniyle aynı fix birebir uygulanamayabilir. Regression tests kritik akışları doğrulamalıdır. Release notes gerekli müşteri aksiyonunu açıkça belirtmelidir.

Emergency Deprecation

Risk yüksekse normal deprecation window kısaltılabilir. Bu karar açık security exception policy'ye dayanmalıdır. Replacement hazır değilse geçici mitigation sağlanabilir. Client owner'lara doğrudan ve hızlı iletişim yapılmalıdır. Timeline mümkün olduğunca somut tarihlerle verilmelidir.

Breaking Security Fix

Bazen güvenli davranış eski contract'la uyumlu değildir. Authentication veya authorization değişikliği istemcileri etkileyebilir. Güvenlik öncelikli olsa bile migration materyali ve test ortamı sunulmalıdır. Parallel support risk nedeniyle mümkün değilse bu durum açıkça açıklanmalıdır. Support capacity kritik client'lar için artırılabilir.

Customer Communication

Security kaynaklı migration mesajı kullanıcıya ne yapması gerektiğini net biçimde anlatmalıdır. Gereksiz hassas teknik detaylar paylaşılmadan risk seviyesi ve deadline belirtilmelidir. E-posta, dashboard ve support outreach birlikte kullanılabilir. Client completion telemetry ile doğrulanmalıdır. Tarih değişiklikleri tüm kanallarda senkron güncellenmelidir.

Normal Support Policy'den İstisnalar

Security exception policy normal support window'un hangi koşullarda kısalabileceğini tanımlar. Kullanıcılar bu olasılığı önceden bilir. İstisna keyfi değil, belirli risk kriterlerine dayanmalıdır. Karar kayıt altına alınmalı ve sonradan review edilmelidir. Böylece güvenlik ile lifecycle öngörülebilirliği arasında dengeli bir yaklaşım kurulur.

API Contract Testleri CI/CD'ye Nasıl Eklenir?

CI/CD contract testing pipeline'ı OpenAPI lint ile başlayıp breaking diff, provider tests, consumer contracts ve SDK compile tests ile devam edebilir. Amaç API değişikliğini production'a çıkmadan önce farklı açılardan doğrulamaktır. Migration fixture'ları eski gerçek request örneklerinin yeni server'da nasıl davrandığını gösterebilir. Release gate gerekli testlerden biri başarısız olduğunda deployment'ı durdurur. Bu yapı contract governance'ı manuel checklist yerine tekrarlanabilir engineering sürecine dönüştürür.

OpenAPI Lint

Lint kuralları naming, documentation ve schema tasarım standartlarını otomatik kontrol eder. Required description veya operation ID gibi organization rules uygulanabilir. Hata geliştiriciye pull request aşamasında gösterilir. Lint tek başına compatibility testi değildir. Ancak contract kalitesinin tutarlı olmasını sağlar.

Breaking-Change Diff

Eski production spec ile yeni spec otomatik karşılaştırılır. Removed path, type change ve required parameter gibi riskler bulunur. Blocking rule release'i durdurabilir. Warning rule human review gerektirebilir. Diff sonucu pull request comment olarak geliştiriciye sunulabilir.

Provider Tests

Provider tests API server'ın kendi contract'ına uygun davranıp davranmadığını doğrular. Request validation, response schema ve error behavior test edilebilir. Version adapter'lar ayrı senaryolarla çalıştırılmalıdır. Test data production'a benzeyen örnekler içermelidir. Critical business rule'lar da provider seviyesinde korunmalıdır.

Consumer Contract Tests

Consumer contract tests aktif istemcilerin gerçek beklentilerini provider build'e karşı doğrular. Özellikle internal dependency'lerde yüksek değer sağlar. Eski ama production'da aktif consumer version'ları test setinde tutulmalıdır. Usage sona erdiğinde contract retirement yapılabilir. Sonuç deployment compatibility gate'e bağlanabilir.

SDK Generation

OpenAPI değişikliğinden sonra SDK preview otomatik üretilebilir. Generated diff API değişikliğinin client yüzeyini gösterir. Hedef dillerin tamamı veya kritik subset pipeline'da çalıştırılabilir. Generator failure release riskidir. Spec ve SDK artefact aynı release metadata'sını paylaşmalıdır.

SDK Compile Tests

Generated SDK package compile edilerek syntax ve type hataları yakalanır. Daha güçlü modelde gerçek sample apps yeni package ile derlenir. Böylece method rename veya required field etkisi görünür olur. Eski SDK da yeni server'a karşı integration testine alınabilir. Bu çift yönlü test compatibility confidence sağlar.

Migration Fixtures

Migration fixture eski request ve response örneklerini temsil eder. Yeni server build bu fixture'ları işleyerek backward compatibility'yi doğrular. Hassas production verisi anonimleştirilmelidir. Kritik customer scenario'ları ayrı fixture setlerinde tutulabilir. Fixture güncelliği last-seen usage ile ilişkilendirilebilir.

Release Gate

Release gate lint, diff, test ve approval sonuçlarını tek karar noktasında toplar. Breaking change planlıysa ilgili version ve migration metadata'sı zorunlu tutulabilir. Emergency security override ayrı süreçle yapılabilir. Gate developer'a açık hata nedeni göstermelidir. Böylece governance geliştirme hızını gereksiz yavaşlatmadan güvenli change control sağlar.

Golden Client Testleri

Golden client tests desteklenen gerçek client kombinasyonlarını yeni server build'e karşı düzenli çalıştırır. Eski SDK ve yeni server birlikteliği forward compatibility'nin en somut testlerinden biridir. Yeni SDK ile yeni server da current experience'ı doğrular. Test senaryoları yalnızca generated examples değil, gerçek usage pattern'lerinden seçilmelidir. Compatibility matrix hangi golden client'ların release gate içinde tutulacağını tanımlar.

Eski SDK + Yeni Server

Bu kombinasyon additive API evolution'ın eski client'ı bozup bozmadığını gösterir. Yeni field ve enum values burada özellikle önemlidir. Testler kritik endpoint ve error flows'u kapsamalıdır. Desteklenen eski SDK major sürümleri matrix'e göre seçilebilir. Failure API release'i durduracak kadar önemli olabilir.

Yeni SDK + Yeni Server

Current SDK ve current server kombinasyonu yeni feature'ların düzgün çalıştığını doğrular. Generated models, authentication ve retry behavior test edilir. Integration tests package registry'den gerçek artefact kullanabilir. Bu yaklaşım local generated code ile publish edilen package arasındaki farkı yakalar. Release sonrası smoke test de aynı senaryoyu production'da çalıştırabilir.

Supported API Versions

Golden tests yalnızca latest version'a odaklanmamalıdır. Support policy içinde kalan v1 veya previous version davranışı da doğrulanmalıdır. Her aktif version için kritik smoke suite bulunabilir. Trafik azaldıkça test coverage risk bazlı azaltılabilir. Sunset sonrası ilgili suite kaldırılır.

Gerçek Client Usage Pattern'leri

Testlerin gerçek kullanım biçimlerini yansıtması coverage kalitesini artırır. Production telemetry hangi endpoint kombinasyonlarının sık kullanıldığını gösterebilir. Common pagination, retry veya batch akışları fixture'a dönüştürülebilir. Hassas veri kullanılmamalıdır. Bu yaklaşım teorik contract'ta görünmeyen behavioral dependency'leri yakalar.

Compatibility Matrix

Compatibility matrix hangi API ve SDK kombinasyonlarının test edilmesi gerektiğini açıklar. Matrix support sözünün teknik karşılığıdır. CI cost nedeniyle tüm kombinasyonlar her commit'te çalıştırılmayabilir. Critical subset hızlı pipeline'da, full matrix nightly veya release öncesinde çalışabilir. Sonuçlar SDK ve API documentation ile aynı policy'yi yansıtmalıdır.

Production Traffic Replay ile API Compatibility Testi

Production traffic replay gerçek kullanım çeşitliliğini yeni API version'a karşı test etmenin güçlü yollarından biridir. Request'ler güvenli biçimde capture edilip hassas veriler anonimleştirildikten sonra v2 test ortamına gönderilebilir. Response, error ve performance farkları otomatik karşılaştırılabilir. Side-effect içeren request'ler yeniden oynatılırken izolasyon şarttır. Replay testleri özellikle belgelenmemiş client behavior ve nadir edge case'leri bulmada sentetik testlerden daha yüksek değer sağlayabilir.

Request Capture

Request capture yalnızca compatibility testi için gerekli alanları toplamalıdır. Authentication secret ve kişisel veri gibi hassas bilgiler korunmalıdır. Sampling yoğun trafiği yönetilebilir hale getirir. Endpoint ve client cohort dengeli temsil edilmelidir. Capture retention süresi privacy policy ile uyumlu olmalıdır.

Hassas Verileri Anonimleştirme

Replay dataset gerçek kullanıcı verisini olduğu gibi taşımamalıdır. Identifier, token, kişisel alan ve secret'lar güvenli biçimde maskelenmelidir. Anonimleştirme schema semantics'i test edilebilir tutmalıdır. Reversible mask gerekiyorsa erişim kontrolleri sıkı olmalıdır. Security review replay pipeline'ın parçası olmalıdır.

V2'ye Replay

Sanitize edilmiş request'ler v2 test veya shadow environment'a gönderilir. External side-effect dependency'ler stub veya isolated instance kullanmalıdır. Request order gerekiyorsa session grouping korunabilir. Replay throughput production pattern'ini taklit edebilir. Server logları her request'i replay olarak açıkça işaretlemelidir.

Response Diff

V1 baseline ve v2 response semantic olarak karşılaştırılır. Bilinçli field farkları allowlist ile filtrelenir. Dynamic timestamp veya request ID gibi alanlar normalize edilir. Beklenmeyen schema ve value farkları raporlanır. Kritik mismatch manual review'a yönlendirilir.

Error Diff

V1 success verirken v2 error üretmesi yüksek riskli sinyaldir. Status code ve machine-readable error code ayrı karşılaştırılmalıdır. Validation rule farkları sık mismatch kaynağıdır. Client cohort bazında error distribution incelenebilir. Bu bulgular migration guide ve server fix'lerine dönüşebilir.

Performance Diff

Replay yalnızca correctness değil performance karşılaştırması da sağlayabilir. V2 latency distribution v1 baseline ile karşılaştırılır. Yeni serialization veya adapter overhead görünür olur. Test environment kapasite farkları sonuç yorumunda dikkate alınmalıdır. Büyük regression production canary öncesinde çözülmelidir.

API Versioning Policy Nasıl Yazılır?

API versioning policy organizasyonun hangi değişiklikte yeni version açacağını ve eski version'ı nasıl yöneteceğini açık biçimde tanımlar. Versioning method, breaking change definition, support window, deprecation window ve security exception temel bölümlerdir. Communication channels, SDK policy ve sunset criteria da aynı dokümanda yer almalıdır. Policy yalnızca platform ekibinin bildiği iç belge olmamalı, API sağlayan ekiplerin günlük development sürecine bağlanmalıdır. Otomatik lint ve CI gate bu kuralları uygulanabilir hale getirir.

Versioning Method

Policy path, header, date veya başka hangi version selection yönteminin kullanılacağını açıkça söyler. Aynı organizasyonda gereksiz farklılık developer experience'ı zorlaştırır. İstisna gerektiren use case'ler için approval süreci tanımlanabilir. Default version behavior ayrıca belirtilmelidir. Gateway ve SDK implementasyonu policy ile uyumlu olmalıdır.

Breaking Change Definition

Removed field, type change, required parameter ve status code değişiklikleri gibi örnekler açıkça listelenmelidir. Behavioral breaking change de tanım içine alınmalıdır. Additive enum change gibi gri alanlar warning kategorisinde ele alınabilir. Definition OpenAPI diff rule set ile aynı olmalıdır. Böylece developer ve CI aynı kavramı kullanır.

Support Window

Her major version için minimum support süresi belirtilmelidir. Public ve internal API için farklı policy olabilir. Süre deprecation notice ile birlikte açıklanmalıdır. Support kapsamının security fix, bug fix veya feature içerip içermediği net olmalıdır. İstisna extension süreci ayrıca tanımlanmalıdır.

Deprecation Window

Deprecation ile sunset arasında minimum migration zamanı bulunmalıdır. Bu süre client release cycle gerçekliğine dayanmalıdır. Replacement hazır olmadan window başlamamalıdır. Runtime header ve notification zamanlaması policy içinde bulunabilir. Kalan client'ların nasıl takip edileceği de açık olmalıdır.

Security Exception

Security issue normal lifecycle kurallarının hızlandırılmasını gerektirebilir. Policy hangi risk seviyesinde exception uygulanabileceğini tanımlamalıdır. Approval ve communication sorumluları önceden belirlenmelidir. Mümkünse compatibility mitigation seçenekleri listelenebilir. Böylece acil durumda karar süreci daha hızlı işler.

Communication Channels

Developer dashboard, e-posta, changelog, runtime header ve support outreach hangi durumda kullanılacağıyla birlikte yazılmalıdır. Kritik sunset yalnızca tek kanala bırakılmamalıdır. Contact inventory güncelliği policy'nin parçası olmalıdır. Message template ortak bilgi alanlarını standartlaştırabilir. Communication evidence audit için saklanabilir.

SDK Policy

SDK Semantic Versioning, support matrix ve EOL kuralları API policy ile uyumlu olmalıdır. Hangi API version için hangi SDK major sürümü desteklendiği belirtilmelidir. Generated SDK deprecation behavior tanımlanmalıdır. Minimum runtime support da aynı bölümde açıklanabilir. API sunset ile package deprecation takvimi çelişmemelidir.

Sunset Criteria

Sunset yalnızca takvim tarihi değil, traffic ve client readiness kriterleri de kullanabilir. Active v1 client count, critical consumer ve support ticket durumu değerlendirilebilir. Kriterlerin hiç uygulanmaması policy'yi etkisiz hale getirir. İstisna approval süreci bulunmalıdır. Removal sonrası response ve cleanup adımları da belirtilmelidir.

Public API ve Internal API Versioning Politikaları Neden Farklı Olmalıdır?

Public ve internal API'lerin temel farkı consumer ownership ve coordination cost'tur. Internal client sahibi ekipler bilindiği için migration doğrudan koordine edilebilir. Public API'de binlerce bağımsız istemcinin release takvimi sağlayıcı tarafından kontrol edilemez. Bu nedenle public policy daha uzun notice, güçlü backward compatibility ve çok kanallı iletişim gerektirir. Internal API ise güçlü contract testing ve dependency mapping sayesinde daha kısa fakat yine öngörülebilir migration pencereleri kullanabilir.

Client Ownership

Internal API consumer owner'ı organizasyon içinde bulunabilir. Public client sahibi ise yalnızca registration metadata üzerinden bilinebilir. Ownership bilinmiyorsa migration outreach zorlaşır. Client ID ve contact collection public platformlarda bu nedenle önemlidir. Policy owner bulunmayan trafik için ayrı işlem tanımlamalıdır.

Coordination Cost

Internal ekiplerle ortak planning yapmak nispeten kolaydır. Public kullanıcılarla birebir koordinasyon maliyeti çok daha yüksektir. Automation, dashboard ve runtime warning bu ölçek sorununu azaltır. Support window coordination cost ile birlikte uzayabilir. Büyük partner'lar public API kullanıyor olsa bile özel outreach gerektirebilir.

Contract Enforcement

Internal organizasyonda lint ve contract testing tüm ekiplerde zorunlu hale getirilebilir. Public consumer'lara kendi parser davranışını zorunlu kılmak daha zordur. Bu nedenle provider tarafı daha konservatif evolution yaklaşımı kullanmalıdır. Forward-compatible SDK sunmak riskleri azaltır. Contract documentation açık ve uzun ömürlü olmalıdır.

Migration Deadline

Internal deadline ekip planına doğrudan eklenebilir. Public API deadline kullanıcıların farklı takvimlerine uyacak kadar önceden duyurulmalıdır. Deadline değişiklikleri güven kaybı yaratmamak için dikkatle yönetilmelidir. Security istisnaları ayrı tutulmalıdır. Client telemetry geçiş hızını ölçer.

Internal Dependency Graph

Internal API'lerde dependency graph hangi servislerin hangi provider'a bağlı olduğunu gösterir. Breaking change impact analizi bu graph üzerinden yapılabilir. Consumer owner ve deployed version metadata'sı eklenirse migration planı otomatik oluşturulabilir. Public API'de bu kadar ayrıntılı dependency bilgisi çoğu zaman bulunmaz. Bu yüzden internal platformlarda graph tabanlı governance yüksek değer sağlar.

Microservice API Evolution

Microservice API evolution teknik contract kadar organizasyonel coupling problemidir. Provider ve consumer farklı ekipler tarafından sahiplenildiğinde küçük breaking change bile coordination maliyeti yaratabilir. Consumer-driven contract testing, dependency mapping ve açık ownership bu riski azaltır. Servisler bağımsız deploy edilebilmeli, fakat bağımsızlığın contract sorumluluğunu ortadan kaldırmadığı unutulmamalıdır. Daha kapsamlı servis iletişimi ve keşif bağlamı için https://www.diyarbakiryazilim.com.tr/posts/mikroservislerde-servis-kesfi-service-discovery-ve-yonetimi adresindeki içerik de yararlı bir devam kaynağıdır.

Service Owner

Her service'in contract değişikliklerinden sorumlu bir owner'ı bulunmalıdır. Owner provider release ve migration iletişimini koordine eder. Ownership değiştiğinde service catalog güncellenmelidir. Sahipsiz API'ler breaking change riskini artırır. Platform governance owner bilgisini zorunlu metadata haline getirebilir.

Consumer Owner

Provider kadar consumer owner bilgisi de önemlidir. Breaking change çıktığında kimle iletişim kurulacağı bilinmelidir. Dependency graph consumer repository veya team metadata'sıyla eşleştirilebilir. Contract test failure doğrudan doğru owner'a yönlendirilebilir. Bu yaklaşım cross-team migration süresini kısaltır.

Organizational Coupling

Teknik olarak küçük API değişikliği birçok ekibin release planını etkileyebilir. Bu durum organizational coupling oluşturur. Additive evolution ve contract tests coupling maliyetini azaltır. Büyük breaking migration'lar yalnızca teknik refactor değeri için yapılmamalıdır. Değişikliğin business faydası coordination cost ile birlikte değerlendirilmelidir.

Consumer Lock-In

Consumer belirli undocumented behavior'a bağımlı hale geldiğinde provider'ın evolve etmesi zorlaşır. Contract clarity ve observability bu bağımlılığı görünür hale getirir. Shared database veya internal implementation detail exposure lock-in'i daha da artırabilir. API boundary açık tutulmalıdır. Consumer feedback yeni contract tasarımında erken alınmalıdır.

Contract Testing

Microservice ortamında contract testing provider ve consumer'ların bağımsız release yapmasına destek olur. Consumer beklentisi pull request aşamasında doğrulanabilir. Full end-to-end environment ihtiyacı azalır. Contract'ların gereksiz implementation detail içermemesi önemlidir. Active consumer version'ları registry ile izlenebilir.

Dependency Mapping

Dependency mapping hangi service'in hangi endpoint veya version'ı kullandığını gösterir. Telemetry static code analysis ile birleştirilebilir. Breaking change impact report otomatik üretilebilir. Migration progress graph üzerinde gösterilebilir. Bu görünürlük sunset kararını çok daha güvenli hale getirir.

API Gateway'de Version Analytics

API gateway tüm request'lerin geçtiği merkezi nokta olduğu için version analytics için doğal bir veri kaynağıdır. Client ID, version, endpoint ve timestamp standart log alanlarına dönüştürülebilir. Deprecated route usage ve last-seen client verileri buradan migration dashboard'a aktarılabilir. Bu yaklaşım her backend servisinin ayrı telemetry implementasyonu yazmasını azaltır. Yine de business kritikliği ve owner gibi metadata gateway logundan değil client inventory sisteminden tamamlanmalıdır.

Client ID + Version

Client ID ve version aynı log kaydında tutulduğunda hangi consumer'ın hangi contract'ı kullandığı netleşir. Bu veri migration outreach için doğrudan kullanılabilir. Unknown veya missing client ID ayrı kategori olmalıdır. SDK version eklenirse daha geniş compatibility resmi oluşur. Privacy gereksinimleri metadata tasarımında dikkate alınmalıdır.

Version Traffic

Version traffic zaman serisi adoption trendini gösterir. V1 düşüşü ve v2 büyümesi aynı grafikte izlenebilir. Endpoint veya region filtreleri rollout problemine işaret edebilir. Sudden rollback v1 trafiğinde artış olarak görünür. Migration hedefleri bu metric üzerinden ölçülebilir.

Deprecated Route Usage

Deprecated route usage yalnızca major version değil endpoint bazında lifecycle yönetimi sağlar. Bir v1 client bazı deprecated endpoint'leri hiç kullanmıyor olabilir. Bu bilgi targeted migration scope oluşturur. High-risk route'lar ayrı alert üretebilir. Removal sonrasında kalan çağrılar support sinyaline dönüşür.

Last-Seen Client

Gateway timestamp bilgisi her client için last-seen hesaplamayı kolaylaştırır. Seyrek batch job'lar yeterli gözlem penceresiyle değerlendirilmelidir. Client migrated olarak işaretlenmeden önce eski version'da trafik kesildiği doğrulanabilir. Aniden geri dönen legacy client alert oluşturabilir. Bu veri inventory ile otomatik senkronize edilebilir.

Migration Dashboard

Gateway analytics migration dashboard'un teknik veri katmanını sağlar. Client owner, deadline ve status business metadata ile zenginleştirilir. Dashboard engineering, support ve product ekiplerinin aynı tabloya bakmasını sağlar. Manual spreadsheet yerine güncel telemetry kullandığı için daha güvenilirdir. Sunset readiness raporu otomatik üretilebilir.

API Lifecycle Automation

API lifecycle automation version release'ten route removal'a kadar tekrar eden adımları standardize eder. Documentation publish, SDK generation, changelog, deprecation header ve client notification aynı workflow içinde bağlanabilir. Sunset alert yaklaşırken owner'lara otomatik hatırlatma gönderebilir. Route removal ise readiness gate ve approval sonrasında uygulanabilir. Bu otomasyon insan kararını kaldırmaz, fakat unutulan adımları ve farklı ekiplerdeki tutarsız uygulamaları azaltır.

Version Release

Yeni version release contract artefact, deployment ve metadata'nın birlikte yayınlanmasını kapsar. Version registry release tarihini kaydeder. Support window otomatik hesaplanabilir. Gateway routing ve documentation aynı release ID ile senkronize edilir. Böylece version başlangıcı açık bir lifecycle olayı haline gelir.

Documentation Publish

OpenAPI release edildiğinde version-specific documentation otomatik üretilebilir. Version picker current sürümü günceller. Previous version status bilgisi değiştirilebilir. Migration guide varsa ilgili link eklenir. Documentation deploy failure API release gate içinde kontrol edilebilir.

SDK Generation

Version release SDK generation pipeline'ını tetikleyebilir. Preview ve final package contract commit'e bağlanır. Hedef diller testlerden geçer. Compatibility matrix otomatik güncellenebilir. Package publish ayrı approval gerektirebilir.

Changelog

OpenAPI diff ve commit metadata changelog taslağı oluşturmak için kullanılabilir. Developer human-readable açıklamayı tamamlar. Breaking veya deprecated change otomatik etiketlenebilir. Release ve effective date kaydedilir. Changelog kullanıcıya tek ve düzenli history sunar.

Deprecation Header

Version registry deprecated durumuna geçtiğinde gateway response header otomatik ekleyebilir. Tarih ve migration metadata merkezi config'ten okunur. Böylece servislerin tek tek kod değiştirmesi gerekmez. Header behavior staging'de test edilir. Client telemetry deprecation warning'lerini ölçebilir.

Client Notification

Deprecated version kullanan active client listesi analytics'ten otomatik çıkarılabilir. Owner ve contact bilgilerine göre notification workflow başlatılır. Mesaj version, deadline ve migration linkini içerir. Gönderim ve acknowledgement durumu dashboard'a yazılır. Kritik client'lar manual outreach kuyruğuna eklenebilir.

Sunset Alert

Sunset tarihi yaklaştıkça platform ekibi ve client owner'lar otomatik uyarı alabilir. Alert kalan traffic ve active client sayısını içerir. Readiness criteria karşılanmıyorsa blocker listesi gösterilir. Bu yaklaşım son haftada beklenmeyen sürprizleri azaltır. Alert cadence sunset yaklaştıkça artırılabilir.

Route Removal

Route removal otomatik workflow içinde approval gerektiren son adım olabilir. Readiness gate sonucu kayıt altına alınır. Gateway configuration eski route'u kapatır. 410 veya structured error policy devreye girer. Legacy monitoring ve infrastructure cleanup ticket'ları otomatik oluşturulabilir.

İstemcilere Deprecation Nasıl Bildirilmelidir?

Deprecation iletişimi tek bir e-posta veya changelog kaydına bırakılmamalıdır. Response headers, developer dashboard, e-posta, SDK warning, CLI warning ve support outreach birbirini tamamlayan kanallardır. En etkili yöntem gerçek API kullanımına yakın sinyali doğrudan client owner iletişimiyle birleştirmektir. Her mesaj replacement, deadline ve migration dokümantasyonunu aynı şekilde göstermelidir. İletişim başarısı yalnızca mesaj gönderimiyle değil, version usage düşüşüyle ölçülmelidir.

Response Headers

Runtime header deprecated endpoint'i gerçekten kullanan client'a doğrudan sinyal verir. SDK veya gateway bu bilgiyi loglayabilir. İnsan kullanıcı header'ı her zaman görmeyeceği için başka kanallarla desteklenmelidir. Header değerleri machine-readable olmalıdır. Monitoring bu sinyali migration metric'e dönüştürebilir.

Developer Dashboard

Developer dashboard kullanıcıya kendi client'larının hangi deprecated version'ı kullandığını gösterebilir. Request count, last-seen ve sunset tarihi aynı ekranda sunulabilir. Migration guide bağlantısı doğrudan ilgili version'a yönlendirilmelidir. Notification banner yüksek görünürlük sağlar. Migration tamamlandığında warning otomatik kaybolabilir.

E-posta

E-posta teknik contact'a timeline ve aksiyon bilgisi ulaştırır. Subject version ve deadline'ı açıkça belirtmelidir. Genel marketing metni yerine doğrudan migration bilgisi verilmelidir. Açılmayan veya bounce olan contact'lar inventory problemi olarak işaretlenmelidir. Kritik client'lar için yalnızca e-postaya güvenilmemelidir.

Changelog

Changelog deprecation'ın resmi release history kaydını oluşturur. Kullanıcı daha sonra timeline'ı doğrulayabilir. Effective date ve replacement burada görünür olmalıdır. Changelog subscription imkanı varsa aktif kullanıcılar otomatik haberdar edilebilir. Runtime kullanım bilgisiyle birleştiğinde daha güçlü olur.

SDK Warning

SDK deprecated operation kullanıldığında compile veya runtime warning gösterebilir. Mesaj replacement method ve sunset bilgisini içermelidir. Warning geliştiricinin günlük workflow'una yakın olduğu için etkilidir. Gereksiz tekrar azaltılmalıdır. Telemetry warning sayısını merkezi olarak raporlayabilir.

CLI Warning

CLI kullanıcıları package veya dashboard duyurusunu görmeyebilir. Komut çalıştırıldığında deprecated API response algılanıp terminal warning gösterilebilir. Mesaj kısa, actionable ve kolay kopyalanabilir URL içermelidir. Exit code normal çalışmayı deprecation döneminde bozmamalıdır. Sunset sonrasında ayrı error handling uygulanabilir.

Support Outreach

Yüksek değerli veya geciken client'lara support ekibi doğrudan ulaşabilir. Dashboard hangi consumer'ın ne kadar trafik ürettiğini gösterir. Görüşmede teknik blocker ve release planı kaydedilebilir. Follow-up tarihi migration status'a eklenir. Bu insan temas noktası büyük enterprise migration'larında çoğu zaman kritik fark yaratır.

Client SDK Deprecation Uyarılarını Nasıl Kullanabilir?

SDK runtime response içindeki deprecation ve sunset sinyallerini geliştiricinin kolay fark edeceği uyarılara dönüştürebilir. Header parse edildikten sonra log warning, telemetry metric veya developer alert üretilebilir. CI test ortamında deprecated endpoint çağrıları warning hatta kontrollü failure olarak işaretlenebilir. Ama production request deprecation döneminde çalışmaya devam etmelidir. SDK bu mekanizmayı central warning policy ile yöneterek her endpoint için ayrı kod ihtiyacını azaltabilir.

Deprecation Header Parse Etme

SDK HTTP response interceptor seviyesinde deprecation header'ı okuyabilir. Parse sonucu request endpoint ve client context ile ilişkilendirilir. Hatalı veya eksik header SDK request'ini bozmamalıdır. Standard format test fixture'larıyla doğrulanmalıdır. Parsed metadata user-facing warning'e dönüştürülebilir.

Sunset Date

SDK sunset tarihini parse ederek warning urgency seviyesini artırabilir. Örneğin tarih yaklaşınca daha görünür log üretilebilir. Timezone ve date parsing güvenilir olmalıdır. SDK kendi saatinin yanlış olabileceğini de göz önünde bulundurmalıdır. Tarih yalnızca bilgilendirme sinyali olarak kullanılmalı, request'i otomatik durdurmamalıdır.

Log Warning

Log warning geliştiriciye kullanılan operation'ın deprecated olduğunu gösterir. Mesaj endpoint, replacement ve deadline içerirse daha faydalıdır. Aynı warning her request'te tekrarlanırsa log noise oluşur. SDK process başına veya belirli interval'da deduplicate edebilir. Logging level policy açıkça belgelenmelidir.

Telemetry Metric

SDK deprecated operation usage için metric üretebilir. Uygulama sahibi kendi observability sisteminde bu sayıyı görebilir. Endpoint ve sunset label'ları migration planlamasına yardım eder. Kişisel veri veya sensitive payload metric'e eklenmemelidir. CI ve production metric'leri ayrı tutulabilir.

Developer Alert

Developer platform telemetry metric'i dashboard alert'e dönüştürebilir. Aktif deprecated call bulunduğunda owner'a notification gönderilebilir. Alert migration documentation linkini içermelidir. Completed client'ta yeni legacy request görülürse regression alert üretilebilir. Bu yaklaşım migration'ın sürekli izlenmesini sağlar.

CI Warning

Integration tests deprecated endpoint çağırıyorsa SDK warning CI logunda görünür hale getirilebilir. Organizasyon isterse yeni code'da deprecated API kullanımını failure yapabilir. Existing legacy tests geçici allowlist kullanabilir. Böylece yeni kullanım artışı engellenir. Sunset yaklaşırken policy daha sıkı hale getirilebilir.

API Versiyonlamada En Sık Yapılan Hatalar

REST API versioning projelerinde sorunların çoğu teknik yöntemin seçiminden değil, lifecycle ve istemci yönetiminin eksik kalmasından çıkar. Her değişiklikte yeni version açmak kadar gerçek breaking change'i minor detay saymak da risklidir. Additive field ve enum genişletmelerinin tüm client'larda güvenli olduğu varsayımı production problemlerine yol açabilir. Deprecation ile sunset'in aynı kavram sayılması veya kullanım ölçmeden route kapatılması da sık görülen hatalardır. REST API Versiyonlama Stratejileri ve İstemci Yönetimi başarılı olacaksa OpenAPI, contract tests, SDK ve client inventory birlikte ele alınmalıdır.

Her Değişiklikte Yeni Version Açmak

Yeni endpoint veya optional field için v2 açmak version proliferation yaratır. Her version uzun süreli support maliyeti taşır. Önce additive evolution seçenekleri değerlendirilmelidir. Breaking criteria policy ile belirlenmelidir. Version numarası değişiklik yönetiminin tek aracı değildir.

Breaking Change'i Minor Değişiklik Sanmak

Küçük görünen type veya status code farkı client behavior'ı kırabilir. Developer kendi server implementasyonuna bakarak etkiyi küçümseyebilir. Client perspective review bu hatayı azaltır. SDK diff ve consumer tests gerçek etkiyi gösterir. Breaking tanımı örneklerle policy'de bulunmalıdır.

Response Field Eklemeyi Mutlak Güvenli Saymak

Yeni response field genellikle additive olsa da strict deserializer kullanan client'lar hata verebilir. Eski SDK ile yeni server testi bu riski gösterir. Unknown field tolerance SDK tasarımında teşvik edilmelidir. Public API'de geniş client çeşitliliği nedeniyle assumption dikkatle yapılmalıdır. Additive changes için de test gerekir.

Enum Expansion Riskini Görmezden Gelmek

Yeni enum value exhaustive switch ve generated enum modellerini etkileyebilir. Client unknown fallback desteklemiyorsa runtime failure oluşabilir. OpenAPI diff enum addition için warning üretmelidir. SDK forward compatibility testleri bu senaryoyu kapsamalıdır. API design open enum yaklaşımını açıkça belgelemelidir.

Default Olarak Otomatik En Yeni Version'ı Seçmek

Version belirtmeyen client'ı otomatik latest contract'a taşımak beklenmeyen breaking change oluşturabilir. Default sabit kalmalı veya explicit version zorunluluğu kullanılmalıdır. Yeni version release'i eski client davranışını değiştirmemelidir. Missing version traffic ayrıca ölçülmelidir. Migration bilinçli client seçimiyle yapılmalıdır.

Deprecation ve Sunset'i Aynı Şey Sanmak

Deprecation kullanımın artık önerilmediğini, sunset ise erişimin sona ermesinin planlandığı zamanı ifade eder. İkisini aynı gün uygulamak migration window'u ortadan kaldırır. Replacement hazır olduktan sonra deprecation başlamalıdır. İstemciye yeterli geçiş süresi verilmelidir. Runtime sinyalleri iki kavramı ayrı göstermelidir.

Kullanımı Ölçmeden Eski Version'ı Kapatmak

Toplam trafikte düşük görünen version kritik tek bir customer tarafından kullanılabilir. Client ID ve last-seen bilgisi olmadan bu risk görülmez. Sunset readiness dashboard'a dayanmalıdır. Unknown traffic investigation yapılmalıdır. Kapatma kararı varsayım yerine gerçek usage evidence kullanmalıdır.

Migration Guide Yayınlamamak

“V2'ye geçin” mesajı geliştiriciye nasıl geçeceğini söylemez. Field mapping, endpoint changes ve SDK upgrade açıkça belgelenmelidir. Before ve after örnekleri support yükünü azaltır. Deadline ve testing checklist rehberde bulunmalıdır. Rehber version release ile aynı anda hazır olmalıdır.

SDK'ları API'den Bağımsız Güncellemek

SDK ve API ayrı version yaşam döngülerine sahip olsa da contract ile senkron kalmalıdır. Yanlış spec'ten generated package ciddi drift oluşturabilir. Compatibility matrix hangi kombinasyonların desteklendiğini göstermelidir. CI generation ve integration tests bu riski azaltır. API release notes ilgili SDK update'ini belirtmelidir.

Error Response'larını Contract Dışı Saymak

Client'lar error code ve status üzerinden otomatik logic çalıştırır. Hata formatını rastgele değiştirmek success schema kadar kırıcı olabilir. OpenAPI error models tanımlanmalıdır. SDK exception mapping test edilmelidir. Error evolution version policy içinde açıkça yer almalıdır.

OpenAPI Spec'i Güncel Tutmamak

Eski OpenAPI documentation, SDK ve diff automation'ı yanlış yönlendirir. Spec server release'in zorunlu artefact'ı olmalıdır. Runtime validation veya integration tests drift'i yakalayabilir. Pull request sürecinde contract change review yapılmalıdır. Tek source of truth yaklaşımı manuel farklılıkları azaltır.

Contract Test Yapmamak

Schema diff gerçek consumer usage'ı her zaman göstermez. Contract tests kritik client beklentilerini korur. Özellikle internal microservices ve mobile backend'de yüksek değer sağlar. Test yoksa breaking behavior staging veya production'da fark edilebilir. CI release gate içinde contract verification bulunmalıdır.

Eski Client'ları Production'da Test Etmemek

Yeni server yalnızca current SDK ile test edilirse forward compatibility sorunları kaçabilir. Support policy içinde kalan eski SDK'lar golden client suite'e eklenmelidir. New response fields ve enum values özellikle test edilmelidir. Usage sona eren client version testten kontrollü kaldırılabilir. Böylece support sözü gerçek test coverage ile desteklenir.

Production-Ready API Versioning Checklist

Production-ready versioning yalnızca URL formatını seçmiş olmak değildir. Contract tanımı, explicit version seçimi, client inventory, testing, lifecycle ve observability birlikte hazır olmalıdır. Checklist release review sırasında ekiplerin kritik bir alanı unutmasını engeller. Her madde mümkün olduğunca otomatik test veya dashboard verisiyle doğrulanmalıdır. Aşağıdaki başlıklar yeni version yayına çıkmadan ve eski version sunset edilmeden önce tekrar gözden geçirilmelidir.

Contract

Contract bölümü API'nin neyi stabil kabul ettiğini açıkça tanımlar. Request, response, errors ve behavior kapsamı birlikte düşünülmelidir. Breaking change tanımı tüm ekiplerce bilinmelidir. OpenAPI bu sözleşmenin machine-readable temsilini sunmalıdır. Release öncesi contract review zorunlu hale getirilebilir.

Breaking change tanımı var mı?

Ekip hangi değişikliğin client migration gerektirdiğini yazılı olarak biliyor olmalıdır. Removed field ve required parameter gibi örnekler policy'de bulunmalıdır. Behavioral değişiklikler de kapsam içine alınmalıdır. CI rule set bu tanımla uyumlu olmalıdır. Belirsiz durumlar için API review owner'ı belirlenmelidir.

OpenAPI güncel mi?

OpenAPI dosyası production server ile aynı contract'ı temsil etmelidir. Documentation ve SDK bu dosyadan üretilebilir. Drift testleri release pipeline'da çalışmalıdır. Version metadata doğru olmalıdır. Eski spec artefact'ı diff baseline olarak saklanmalıdır.

Version

Version seçimi istemci açısından açık ve öngörülebilir olmalıdır. Path, header veya başka yöntem organizasyon standardına uymalıdır. Default davranış sürpriz migration yaratmamalıdır. Support window release öncesinde tanımlanmalıdır. Version registry lifecycle durumunu merkezi tutabilir.

Version seçimi explicit mi?

İstemci hangi contract'ı kullandığını açıkça belirtebiliyorsa migration daha güvenli olur. Header veya path değeri loglarda görünür olmalıdır. Missing version behavior belgelenmelidir. Otomatik latest seçimi dikkatle değerlendirilmelidir. SDK version seçimini kullanıcı adına doğru biçimde yönetebilir.

Support window tanımlı mı?

Yeni version'ın ne kadar süre destekleneceği baştan bilinmelidir. Client'lar future migration planını buna göre yapar. Public ve internal API için farklı süre olabilir. Security exception policy ayrıca belirtilmelidir. Sunset tarihi daha sonra belirlenebilse bile minimum notice rule açık olmalıdır.

Client

Client yönetimi olmadan version lifecycle kör ilerler. Hangi application'ın hangi version kullandığı bilinmelidir. Owner ve contact bilgileri güncel tutulmalıdır. SDK version ve last-seen telemetry migration riskini daha iyi gösterir. Inventory mümkün olduğunca gateway usage ile otomatik güncellenmelidir.

Client inventory var mı?

Aktif consumer'ların merkezi listesi bulunmalıdır. Client ID, application, team ve owner gibi bilgiler tutulabilir. Unknown traffic ayrıca takip edilmelidir. Inventory deprecation notification için kaynak olur. Güncelliği düzenli olarak doğrulanmalıdır.

Current version biliniyor mu?

Her active client'ın hangi API contract'ı kullandığı telemetry ile ölçülmelidir. Manuel beyan tek başına yeterli değildir. SDK version ile birlikte tutulması faydalıdır. Migration status gerçek trafikle doğrulanabilir. Sunset readiness bu veri olmadan güvenilir değildir.

Testing

Version release testing yalnızca yeni feature happy path'lerini kapsamaz. OpenAPI diff, contract tests ve eski SDK compatibility birlikte çalışmalıdır. Error behavior ve pagination gibi cross-cutting contract alanları da doğrulanmalıdır. Test coverage support matrix ile uyumlu olmalıdır. Release gate sonuçları production deployment'ın ön koşulu olmalıdır.

OpenAPI diff var mı?

Old ve new spec otomatik karşılaştırılmalıdır. Removed field, type change ve required parameter gibi riskler görünür olmalıdır. Warning ve breaking seviyeleri policy ile eşleşmelidir. Diff pull request'te developer'a sunulmalıdır. Planned breaking change için migration metadata'sı zorunlu olabilir.

Contract test var mı?

Critical consumer expectations yeni provider build'e karşı doğrulanmalıdır. Internal service ve mobile app gibi önemli client'lar test setinde tutulabilir. Active version usage hangi contract'ların gerekli olduğunu belirler. Failure release'i durdurabilir. Contract retirement kullanım sona erdiğinde yapılmalıdır.

Old SDK test ediliyor mu?

Support edilen eski SDK yeni server response'larıyla düzenli test edilmelidir. New fields, enums ve errors özel fixture'larla kontrol edilmelidir. Bu test forward compatibility için doğrudan kanıt sağlar. Unsupported SDK matrix'ten çıkarılmalıdır. Golden client suite release pipeline'a bağlanabilir.

Lifecycle

Lifecycle planı version'ın yalnızca nasıl başlayacağını değil, nasıl biteceğini de tanımlar. Deprecation, sunset ve migration guide üç ayrı ama ilişkili bileşendir. Replacement hazır olmadan lifecycle kapatma aşamasına geçilmemelidir. Client usage ölçümü her aşamayı desteklemelidir. Tarihler ve sorumlular merkezi registry'de tutulabilir.

Deprecation policy var mı?

Policy ne zaman bir version veya endpoint'in deprecated sayılacağını belirtmelidir. Minimum notice süresi tanımlanabilir. Runtime header ve communication channels belirlenmelidir. Yeni client'ların deprecated contract kullanması sınırlandırılmalıdır. Security exception ayrı kural olarak yazılmalıdır.

Sunset policy var mı?

Sunset kriterleri açık değilse legacy version sürekli yaşayabilir. Traffic threshold, active client ve critical consumer durumu değerlendirilmelidir. Sunset header ve deadline iletişimi standardize edilmelidir. İstisna approval süreci bulunmalıdır. Removal sonrası response davranışı da policy'ye eklenmelidir.

Migration guide var mı?

Her breaking version change için uygulanabilir rehber bulunmalıdır. Endpoint ve field mapping kullanıcıya somut yol gösterir. SDK upgrade ve test checklist dahil edilmelidir. Deadline kolay görünmelidir. Rehber pilot client feedback'iyle iyileştirilebilir.

Observability

Observability migration ve sunset kararlarını gerçek usage verisine bağlar. Version, endpoint, client ID ve SDK version temel telemetry alanlarıdır. Deprecated traffic zaman içinde düşüş göstermelidir. Error rate ve latency v2 adoption kalitesini doğrular. Dashboard tüm ilgili ekiplerin aynı veriye erişmesini sağlar.

Version usage ölçülüyor mu?

Her request'in hangi API version'a ait olduğu log veya metric ile bilinmelidir. Header veya path bilgisi normalize edilmelidir. Daily active client ve traffic share hesaplanabilir. Missing version ayrıca izlenmelidir. Usage trend migration KPI olarak kullanılabilir.

Deprecated traffic ölçülüyor mu?

Deprecated endpoint ve version request'leri ayrı metric olmalıdır. Client ID sayesinde kalan consumer'lar bulunabilir. Last-seen ve error rate migration durumunu tamamlar. Alert sunset yaklaştıkça daha sıkı çalışabilir. Kullanım sıfırlanmadan route kaldırma kararı verilmemelidir.

Uçtan Uca API v1 → v2 Migration Workflow

Uçtan uca v1'den v2'ye migration tek bir deployment değil, contract tasarımından legacy cleanup'a kadar uzanan kontrollü bir süreçtir. Önce breaking changes ve client inventory görünür hale getirilir. Ardından v2 spec, SDK, compatibility tests ve migration guide hazırlanır. Pilot ve shadow testler tamamlandıktan sonra genel rollout yapılır ve v1 deprecation süreci başlatılır. Son adım yalnızca route'u kapatmak değil, eski kod, dokümantasyon ve monitoring yükünü de temizlemektir.

1. Breaking Değişiklikleri Tanımlayın

İlk adım v2 gerektiren gerçek breaking changes listesini çıkarmaktır. Field, endpoint, authentication ve behavior farkları birlikte incelenmelidir. Gereksiz değişiklikler scope'tan çıkarılmalıdır. Her breaking change için business gerekçesi yazılmalıdır. Bu liste migration guide'ın temelini oluşturur.

2. Client Envanterini Çıkarın

V1'i kullanan active client'lar belirlenmelidir. Client ID, owner, SDK version ve last-seen bilgisi toplanmalıdır. Unknown traffic ayrıca araştırılmalıdır. Client type migration window planını etkiler. Inventory tamamlanmadan sunset tarihi belirlemek risklidir.

3. Versioning Stratejisini Belirleyin

V2 path, header veya seçilen kurumsal yöntemle expose edilmelidir. Default version behavior açık olmalıdır. Gateway routing ve cache politikası test edilmelidir. SDK version seçimini desteklemelidir. Seçilen yöntem gelecekteki version'larda da tutarlı kullanılmalıdır.

4. V2 OpenAPI Spec'i Oluşturun

V2 contract önce machine-readable spec olarak tanımlanmalıdır. Request, response, errors ve security dahil edilmelidir. Operation IDs SDK etkisi açısından gözden geçirilmelidir. Deprecated v1 mapping notları hazırlanabilir. Spec design review'dan geçirilmelidir.

5. Breaking-Change Diff Çalıştırın

V1 ve v2 spec structural diff ile karşılaştırılmalıdır. Beklenen tüm breaking changes listede görünmelidir. Beklenmeyen farklar düzeltilmelidir. Enum ve response changes ayrıca incelenmelidir. Diff sonucu migration guide ile eşleşmelidir.

6. Compatibility Adapter Gereksinimini Belirleyin

Bazı v1 davranışlarını yeni backend üzerinde sürdürmek gerekiyorsa adapter değerlendirilebilir. Büyük client base veya pahalı migration bunu haklı çıkarabilir. Adapter canonical business logic'i paylaşmalıdır. Performance ve security etkisi ölçülmelidir. Removal tarihi en baştan belirlenmelidir.

7. V2 SDK'ları Üretin

V2 spec hedef diller için SDK preview build'e dönüştürülmelidir. Generated diff review edilmelidir. Method, type ve enum davranışı test edilmelidir. Package pre-release pilot client'lara sunulabilir. Compatibility matrix güncellenmelidir.

8. Eski Client Contract'larını Test Edin

Yeni server build desteklenen v1 client expectations'ına karşı çalıştırılmalıdır. Old SDK golden tests özellikle önemlidir. Response field ve error behavior farkları kontrol edilmelidir. Failure varsa adapter veya contract düzeltilmelidir. Support window boyunca bu testler korunmalıdır.

9. Migration Guide Yayınlayın

Guide breaking changes, mappings, SDK upgrade ve test checklist içermelidir. Pilot başlamadan önce erişilebilir olmalıdır. Kullanıcı feedback'i dokümana yansıtılmalıdır. Deadline ilk aşamada planlanan timeline ile gösterilebilir. Support contact açıkça belirtilmelidir.

10. Pilot Client'ları V2'ye Taşıyın

Temsil gücü yüksek ve iletişimi kolay client'lar pilot olarak seçilmelidir. Migration gerçek application environment'da yapılmalıdır. Error, latency ve business metrics izlenmelidir. Sorunlar genel rollout öncesinde çözülmelidir. Pilot deneyimi guide ve SDK'yı iyileştirir.

11. Shadow/Parallel Test Yapın

Gerçek v1 request'leri güvenli biçimde v2 ile karşılaştırılabilir. Side-effect endpoint'lerde izolasyon uygulanmalıdır. Response mismatch ve performance farkları ölçülmelidir. Parallel run client-by-client geçişe imkan verir. Confidence yeterli seviyeye geldiğinde rollout genişletilir.

12. V2'yi Genel Kullanıma Açın

V2 production-ready olduğunda yeni client'lar için current version haline getirilebilir. Documentation default v2'yi göstermelidir. SDK stable package olarak yayınlanmalıdır. Monitoring v1 ve v2'yi ayrı izlemelidir. V1 henüz çalışmaya devam eder.

13. V1 Deprecation Tarihini Duyurun

V1 artık yeni entegrasyonlar için önerilmediği açıkça ilan edilmelidir. Announcement replacement ve timeline bilgisi içermelidir. Developer dashboard, changelog ve e-posta birlikte kullanılabilir. Client owner'lara doğrudan bildirim yapılabilir. Duyuru tarihi lifecycle registry'ye kaydedilmelidir.

14. Deprecation Header Ekleyin

V1 response'larına runtime deprecation sinyali eklenmelidir. Gateway central implementation için uygun noktadır. SDK warning bu header'ı kullanabilir. Header staging ve production'da doğrulanmalıdır. Usage telemetry warning kapsamını ölçebilir.

15. Sunset Tarihini Bildirin

Sunset tarihi client'lara geçişin tamamlanması gereken net hedefi verir. Tarih support policy ile uyumlu olmalıdır. Runtime Sunset header ve documentation aynı bilgiyi taşımalıdır. Critical clients özel timeline görüşmesi yapabilir. Değişiklik olursa tüm kanallar senkron güncellenmelidir.

16. V1 Kullanımını Client Bazında İzleyin

Dashboard her client'ın v1 request count ve last-seen bilgisini göstermelidir. Traffic share tek başına yeterli değildir. SDK version ve owner metadata'sı eklenmelidir. Migration status telemetry ile doğrulanmalıdır. Geri dönen legacy traffic alert oluşturabilir.

17. Kalan İstemcilere Doğrudan Ulaşın

Sunset yaklaşırken aktif v1 consumer'lara hedefli outreach yapılmalıdır. Mesaj mevcut usage ve deadline bilgisini içermelidir. Blocker teknik veya organizasyonel olarak kaydedilmelidir. Support gerekli örnek veya test ortamını sağlamalıdır. Follow-up tarihi dashboard'da tutulmalıdır.

18. Sunset Readiness Kontrolü Yapın

Traffic, active clients, critical consumers ve support tickets birlikte değerlendirilmelidir. Security riskleri ve exception'lar gözden geçirilmelidir. Kriterler karşılanıyorsa removal onayı verilebilir. Karar kayıt altına alınmalıdır. Gereksiz belirsizlik yerine önceden yazılmış gate kuralları kullanılmalıdır.

19. V1'i Kapatın

Gateway route veya v1 adapter sunset tarihinde devre dışı bırakılabilir. Eski request'ler structured 410 response alabilir. Migration documentation hâlâ erişilebilir tutulmalıdır. Remaining traffic monitoring devam etmelidir. Kritik beklenmeyen client görülürse exception policy uygulanabilir.

20. Legacy Kod, Route ve Dokümantasyonu Temizleyin

Migration tamamlandıktan sonra v1 adapter, gateway rule ve eski test fixture'ları gözden geçirilmelidir. Artık gerekli olmayan monitoring ve infrastructure kaldırılmalıdır. Historical migration documentation gerektiği kadar korunabilir. Client inventory v1 status alanları archive edilebilir. Bu cleanup yapılmazsa sunset teknik borcu gerçekten azaltmaz.

REST API Geliştirmek İçin En İyi Programlama Dili Hangisidir?

REST API geliştirmek için tek bir “en iyi” programlama dili yoktur. TypeScript, Python, Go, Java ve C# farklı ekip deneyimleri ve operasyonel ihtiyaçlar için güçlü seçenekler sunar. API'nin uzun ömürlü başarısını asıl belirleyen dil değil, contract tasarımı, testing, observability, security ve lifecycle disiplinidir. Aynı iyi versioning ilkeleri kullanılan programlama dilinden bağımsız olarak uygulanabilir. Ekip yetkinliği, runtime maliyeti, performans ihtiyacı ve mevcut ekosistem birlikte değerlendirilmelidir.

TypeScript

TypeScript frontend ve backend arasında tip paylaşımı yapılan ekiplerde güçlü developer experience sunabilir. Node.js tabanlı framework'lerle REST API geliştirme hızlıdır. OpenAPI generation ve typed SDK süreçleri kolayca entegre edilebilir. Runtime validation'ın compile-time types ile karıştırılmaması gerekir. Contract her zaman dış istemcinin görebildiği davranış üzerinden tanımlanmalıdır.

Node.js ekosistemi

Node.js ekosistemi HTTP server, validation, testing ve observability için geniş seçenekler sunar. Event-driven runtime yüksek concurrency gerektiren birçok API iş yükünde uygun olabilir. Framework seçimi versioning stratejisinden bağımsız tutulmalıdır. Gateway, OpenAPI ve CI süreçleri standart HTTP contract üzerinden çalışır. Ekip production profiling ve dependency update disiplinini korumalıdır.

Type-safe SDK

TypeScript API'den generated type-safe client üretmek frontend integration hatalarını azaltabilir. Request ve response modelleri compile-time kontrol edilir. Ancak generated type'ların unknown enum ve optional field konusunda aşırı strict olmaması gerekir. SDK preview diff contract etkisini erken gösterir. Package version API contract'tan bağımsız Semantic Versioning ile yönetilebilir.

Python

Python hızlı geliştirme ve geniş backend ekosistemi nedeniyle API projelerinde sık kullanılır. Type hints ve schema tooling contract-first yaklaşımla birleştirilebilir. Runtime validation ve serialization behavior dikkatle test edilmelidir. Performance gereksinimi kullanılan framework ve deployment modeline göre değerlendirilir. Versioning ilkeleri programlama dilinden bağımsız olarak gateway veya application layer'da uygulanabilir.

FastAPI

FastAPI type annotations üzerinden OpenAPI üretimini kolaylaştıran bir Python framework yaklaşımı sunar. Generated spec'in gerçek contract ile senkron kalması yine test edilmelidir. Automatic schema generation developer hızını artırabilir. Breaking change detection için önceki spec artefact ile diff yapılabilir. Framework kullanmak lifecycle policy ihtiyacını ortadan kaldırmaz.

OpenAPI otomasyonu

Python API pipeline OpenAPI spec'i build sırasında üretebilir veya contract-first dosyadan server validation sağlayabilir. Her iki modelde de diff ve lint uygulanmalıdır. SDK generation aynı spec artefact'ını kullanabilir. CI server ile spec drift'ini kontrol etmelidir. Automation contract governance'ın günlük development sürecine girmesini sağlar.

Go

Go düşük runtime overhead ve sade deployment modeli nedeniyle backend API'lerde güçlü bir seçenektir. Statik typing request ve response modellerinde hataları erken yakalayabilir. JSON compatibility davranışı struct tasarımına bağlıdır. OpenAPI generation veya contract-first tooling pipeline'a eklenebilir. Yüksek performans tek başına iyi API anlamına gelmez; lifecycle ve backward compatibility yine temel sorumluluktur.

Yüksek performans

Go yüksek throughput ve düşük kaynak kullanımı gereken servislerde avantaj sağlayabilir. Version adapter ve serialization overhead yine benchmark edilmelidir. Performance SLO'ları v1 ve v2 için ayrı ölçülebilir. Optimization contract behavior'ı sessizce değiştirmemelidir. Load tests migration rollout öncesinde çalıştırılmalıdır.

Cloud-native API'ler

Tek binary deployment ve container kullanım kolaylığı Go'yu cloud-native servislerde pratik hale getirebilir. Service discovery, gateway ve observability standart protokollerle entegre edilebilir. API versioning routing gateway veya service içinde uygulanabilir. Deployment sıklığı yüksek olsa bile public contract version daha yavaş evolve edebilir. Operational release ile contract release ayrımı korunmalıdır.

Java

Java uzun ömürlü enterprise backend sistemlerinde güçlü type sistemi ve geniş araç desteği sunar. Büyük ekiplerde standardization ve testing altyapısı için uygun olabilir. Generated SDK ve OpenAPI tooling kolayca CI'ye eklenebilir. Runtime upgrade politikası client SDK support ile ayrı yönetilmelidir. API contract değişiklikleri framework refactor'larından bağımsız değerlendirilmelidir.

Enterprise API

Enterprise API'ler uzun support window ve partner entegrasyonları nedeniyle güçlü lifecycle governance gerektirebilir. Java ekosistemi bu tür büyük sistemlerde yaygın olsa da asıl konu contract yönetimidir. Authentication, error schema ve version analytics baştan planlanmalıdır. Consumer testing kurumsal dependency riskini azaltır. Change-management süreleri sunset planına dahil edilmelidir.

Spring

Spring tabanlı API'lerde request mapping, validation ve security katmanları versioning ile entegre edilebilir. OpenAPI tooling spec generation veya contract validation sağlayabilir. Annotation değişikliği istemeden endpoint contract'ını değiştirebileceği için diff pipeline önemlidir. Profile veya bean koşulları version behavior'ını aşırı dağıtmamalıdır. Adapter ve gateway yaklaşımı daha merkezi yönetim sağlayabilir.

C# / .NET

C# ve .NET typed API modelleri, güçlü tooling ve enterprise entegrasyon yetenekleri sunar. Nullable reference types request ve response schema kararlarında dikkatli kullanılmalıdır. OpenAPI generation ile SDK pipeline kurulabilir. Versioning middleware veya gateway seviyesinde uygulanabilir. Runtime ve SDK target framework support politikaları API lifecycle ile birlikte planlanmalıdır.

Dil Seçiminden Daha Önemli Olan API Contract Tasarımı

Programlama dili değişebilir, framework yenilenebilir ve deployment platformu dönüşebilir. İstemcinin gördüğü contract ise yıllarca yaşamaya devam edebilir. Bu nedenle stable field semantics, error model, authentication, pagination ve version policy dil seçiminden daha uzun vadeli etki yaratır. İyi contract tasarımı backend'in internal teknolojisini değiştirme özgürlüğünü artırır. Teknik yatırım önceliği sadece framework seçimine değil, test edilebilir ve evolve edilebilir sözleşmeye verilmelidir.

Open Source ve İşbirliği ile API Geliştirme

Açık kaynak araçlar API contract tasarımı, testing, SDK generation ve collaboration süreçlerini hızlandırabilir. OpenAPI Specification ortak sözleşme dili sağlar, contract testing ve diff araçları değişiklik riskini daha erken gösterir. Mock server araçları consumer ekiplerinin provider tamamlanmadan geliştirme yapmasına yardımcı olabilir. Git tabanlı review süreci API design proposal'larını görünür hale getirir. Araç seçerken tek kriter popülerlik değil, ekip workflow'una uyum, bakım durumu ve otomasyon kabiliyeti olmalıdır.

OpenAPI Specification

OpenAPI vendor-independent contract tanımı için temel bir standart yaklaşımı sunar. API design review, documentation ve SDK generation aynı spec üzerinden çalışabilir. Açık ekosistem farklı araçların aynı artefact'ı kullanmasını sağlar. Versioned specs migration diff için güçlü bir history oluşturur. Organizasyon kendi lint rules'u ile kalite standardını ekleyebilir.

Pact

Pact consumer-driven contract testing workflow'larında kullanılabilecek açık kaynak seçeneklerden biridir. Consumer expectations provider verification ile ilişkilendirilebilir. Özellikle internal service ekosisteminde release confidence sağlar. Contract scope gereksiz implementation detail içermemelidir. Araç seçimi organizasyonun deployment ve ownership modeline göre değerlendirilmelidir.

OpenAPI Generator

OpenAPI Generator farklı programlama dilleri için client veya server artefact üretiminde kullanılabilir. Generated SDK pipeline manuel tekrarları azaltabilir. Template ve configuration source control içinde tutulmalıdır. Generator upgrade'leri SDK diff oluşturabileceği için normal dependency update gibi test edilmelidir. Generated output her zaman compile ve integration testlerinden geçmelidir.

API Lint Araçları

Lint araçları naming, description ve schema standartlarını otomatik kontrol eder. Kurumsal API style guide executable rule set'e dönüşebilir. Developer hatayı documentation review sonuna kadar beklemeden görür. Lint compatibility testinin yerine geçmez. Fakat contract kalitesinde güçlü bir ilk katman sağlar.

Breaking-Change Diff Araçları

Diff araçları old ve new OpenAPI arasındaki riskli değişiklikleri otomatik tespit edebilir. Removed field, required parameter ve type change temel örneklerdir. Rule set organizasyon ihtiyaçlarına göre özelleştirilebilir. Sonuç CI quality gate'e bağlanabilir. Behavioral changes için ek testler gerektiği unutulmamalıdır.

Mock Server Araçları

Mock server consumer ekiplerinin gerçek backend hazır olmadan contract üzerinden geliştirme yapmasını sağlar. Version-specific example ve error response'lar test edilebilir. Mock spec ile aynı kaynaktan üretilmelidir. Aksi durumda mock drift yeni bir problem oluşturur. Contract tests real provider ile mock davranışının farklılaşmasını azaltabilir.

GitHub ile Contract Review

Git tabanlı pull request süreci OpenAPI değişikliklerini normal code review ile aynı akışa taşıyabilir. Diff botları breaking changes hakkında otomatik yorum bırakabilir. SDK preview output reviewer'a client impact gösterebilir. API owner approval zorunlu hale getirilebilir. Değişiklik history ve decision discussion merkezi biçimde saklanır.

API Design Proposal ve Pull Request

Büyük breaking change doğrudan kodla başlamak yerine kısa design proposal ile tartışılabilir. Problem, alternatifler, client impact ve migration planı açıklanır. Consumer ekiplerinden erken geri bildirim alınır. Ardından OpenAPI pull request somut contract değişikliğini gösterir. Bu süreç gereksiz v2 tasarımlarını daha kod yazılmadan önce fark etmeye yardımcı olur.

Yazılımcı Olmak İçin API Alanında Neler Öğrenilmeli?

API geliştirme öğrenmek isteyen bir yazılımcı yalnızca framework endpoint yazmayı değil HTTP, authentication, testing, versioning ve observability temellerini birlikte öğrenmelidir. REST prensipleri ve JSON serialization başlangıç için önemlidir. OAuth 2.0 ve güvenlik konuları gerçek production sistemlerinde kısa sürede gerekli hale gelir. OpenAPI ve contract tests daha profesyonel entegrasyon tasarımı sağlar. Distributed systems ve SDK tasarımı öğrenildiğinde API'nin yalnızca server kodundan ibaret olmadığı daha net görülür.

HTTP

HTTP method, status code, header, caching ve idempotency API tasarımının temelidir. Framework abstraction'ı bu detayları tamamen gizlememelidir. GET ve POST semantics doğru anlaşılmalıdır. Retry ve cache davranışı protocol bilgisinden doğar. Versioning header veya content negotiation kullanıldığında HTTP bilgisi daha da önemli hale gelir.

REST

REST resource odaklı API tasarımını anlamak için temel bir yaklaşım sunar. URL, method ve representation ilişkisi doğru kurulmalıdır. Her business action'ı rastgele RPC endpoint'e dönüştürmek uzun vadede consistency sorunları yaratabilir. Bununla birlikte pratik API tasarımı kullanıcı ihtiyaçlarını da gözetmelidir. Versioning resource modelinin evolution biçimini doğrudan etkiler.

JSON

JSON basit görünse de null, missing field, number ve array semantics gibi ayrıntılar contract açısından önemlidir. Unknown field tolerance forward compatibility'yi etkiler. Enum ve union representation SDK generation'da farklı sonuçlar doğurabilir. Schema validation request ve response davranışını netleştirir. JSON yalnızca format değil, client-server sözleşmesinin önemli parçasıdır.

Authentication

Authentication kullanıcının veya client'ın kimliğini doğrular. API key, token ve session gibi yöntemlerin güvenlik özellikleri öğrenilmelidir. Secret storage ve rotation gerçek production sorumluluğudur. Authentication değişikliği migration gerektirebilir. Authorization ile authentication farkı net anlaşılmalıdır.

OAuth 2.0

OAuth 2.0 delegated authorization ve token tabanlı access modellerini anlamak için önemli bir konudur. Grant türleri, scope ve token lifecycle kavramları öğrenilmelidir. Her API'nin OAuth kullanması zorunlu değildir. Kullanım senaryosu ve threat model yöntemi belirler. Migration sırasında eski credential yöntemiyle paralel çalışma planı gerekebilir.

OpenAPI

OpenAPI contract-first düşünmeyi öğrenmek için güçlü bir araçtır. Schema, response, security ve operation metadata tek dosyada tanımlanabilir. SDK ve documentation generation buna bağlanabilir. Diff ve lint development workflow'u iyileştirir. Spec'i güncel tutma disiplini teknik becerinin önemli parçasıdır.

Testing

API testing unit testten daha geniş düşünülmelidir. Integration, contract, golden client ve replay testleri farklı riskleri yakalar. Error flows ve retry behavior mutlaka test edilmelidir. CI pipeline testsiz breaking change'i production'a bırakmamalıdır. Test design gerçek client usage pattern'lerinden beslenmelidir.

Versioning

Versioning hangi değişikliğin breaking olduğunu anlamayı öğretir. Path veya header seçmek konunun yalnızca küçük bölümüdür. Backward compatibility, deprecation ve migration asıl lifecycle sorumluluklarıdır. Client inventory olmadan version yönetimi eksik kalır. Bu konu backend developer'ı platform düşüncesine yaklaştırır.

Distributed Systems

Distributed systems network failure, timeout, retry ve partial failure gerçeklerini anlamayı sağlar. API request başarılı mı bilinmiyor gibi durumlar bu bilgiyi gerektirir. Idempotency ve eventual consistency gibi kavramlar gerçek contract tasarımını etkiler. Microservice bağımlılıkları version migration riskini büyütür. Bu alan öğrenildikçe API tasarımı daha dayanıklı hale gelir.

Observability

Metrics, logs ve traces production davranışını anlamanın temel araçlarıdır. Version migration için client ID ve version labels özel önem taşır. Error rate ve latency rollout kararını yönlendirir. Last-seen client telemetry sunset riskini azaltır. Observability yalnızca incident çözmek değil, lifecycle yönetmek için de kullanılır.

SDK Tasarımı

SDK tasarımı API'yi başka geliştiricilerin nasıl deneyimlediğini öğretir. Method naming, error mapping ve retry behavior client ergonomisini belirler. Forward compatibility generated model tasarımında önemli bir konudur. Semantic Versioning API contract version'dan ayrı yönetilmelidir. SDK düşünmek API provider'ın consumer perspektifini geliştirmesine yardımcı olur.

Portföy İçin API Versioning Projeleri

API versioning konusunda güçlü bir portföy oluşturmak için yalnızca basit CRUD endpoint göstermek yerine lifecycle problemlerini çözen projeler geliştirmek daha öğreticidir. V1 ve v2 contract, OpenAPI diff pipeline, consumer contracts ve migration dashboard gerçek production pratiklerini yansıtır. Automatic SDK generation ve deprecation middleware de iyi proje konularıdır. Bu projeler HTTP bilgisi kadar CI/CD, observability ve developer experience becerisini de gösterir. Çalışmaları açık biçimde dokümante etmek teknik kararların anlaşılmasını kolaylaştırır.

V1/V2 REST API

Basit bir domain üzerinde v1 ve breaking değişiklik içeren v2 tasarlanabilir. İki version parallel run ile çalıştırılabilir. Migration guide ve OpenAPI specs repository'de tutulabilir. Gateway veya application routing eklenebilir. Proje yalnızca endpoint değil lifecycle yaklaşımını gösterebilir.

OpenAPI Breaking-Change CI Pipeline

Eski ve yeni spec'i karşılaştıran CI pipeline güçlü bir portföy projesidir. Removed field veya required parameter için build failure üretilebilir. Pull request comment breaking reason gösterebilir. Human override ve migration metadata flow eklenebilir. Bu çalışma API governance becerisini somut biçimde gösterir.

Consumer-Driven Contract Testing

İki küçük servis veya frontend-backend çifti üzerinde consumer contract workflow kurulabilir. Consumer expectation publish eder ve provider CI içinde doğrular. Breaking change intentionally yapılarak pipeline failure gösterilebilir. Version metadata ve deployment compatibility eklenebilir. Proje distributed team problemine teknik çözüm sunar.

API Migration Dashboard

Gateway loglarından client ID ve version bilgisi toplayan dashboard geliştirilebilir. V1 traffic share, last-seen ve migration status gösterilebilir. Mock client'lar farklı usage pattern üretir. Sunset readiness score eklenebilir. Böyle bir proje observability ile lifecycle yönetimini birleştirir.

Automatic SDK Generation

OpenAPI değişikliğinde TypeScript ve Python SDK üreten pipeline kurulabilir. Generated diff pull request'e eklenebilir. Test ve package preview artefact oluşturulabilir. Semantic version önerisi breaking diff'e göre hesaplanabilir. Bu proje contract-to-client automation becerisini gösterir.

Deprecation/Sunset Middleware

Middleware route metadata'sına göre deprecation ve sunset header ekleyebilir. Client ID telemetry üretilebilir. Deadline yaklaşınca log severity değişebilir. Structured 410 response sunset sonrasında devreye girebilir. Bu proje lifecycle sinyallerini production request path ile birleştirir.

API Gateway Version Router

Path ve header version selection destekleyen küçük gateway projesi geliştirilebilir. Unsupported version için structured error dönülebilir. Version metrics ve per-version rate limit eklenebilir. Canary routing ile belirli client cohort v2'ye gönderilebilir. Bu proje routing, observability ve migration konularını birlikte gösterir.

Diyarbakır Yazılım Topluluğu İçin API Proje Fikirleri

Diyarbakır Yazılım Topluluğu içinde API odaklı çalışmalar yalnızca eğitim sunmakla kalmaz, katılımcıların birlikte üretmesini de destekleyebilir. Contract-first atölyeleri, v1'den v2'ye migration simülasyonu ve contract testing lab gerçek ekip problemlerini küçük projelerde deneyimleme imkanı verir. Açık kaynak gateway template veya lint rule set geliştirerek topluluk çıktısı kalıcı hale getirilebilir. Mevcut proje çalışmalarını görmek için https://www.diyarbakiryazilim.com.tr/projects adresi incelenebilir. Topluluğun yaklaşımı ve çalışma alanları hakkında daha fazla bilgi için https://www.diyarbakiryazilim.com.tr/about sayfası da yararlı bir başlangıç noktasıdır.

REST API Design Workshop

Workshop katılımcılarının gerçek bir domain için endpoint ve contract tasarlamasına odaklanabilir. Gruplar request, response ve error schema kararlarını birlikte tartışabilir. Son aşamada breaking change senaryosu verilerek versioning kararı istenebilir. Code review benzeri contract review yapılabilir. Böylece REST bilgisi yalnızca teorik sunumla sınırlı kalmaz.

OpenAPI Contract-First Atölyesi

Katılımcılar önce OpenAPI spec yazar, sonra mock server veya backend implementasyonu oluşturabilir. Lint ve documentation generation sürece eklenebilir. V1 spec üzerinde planlı breaking change yapılarak diff çalıştırılabilir. SDK preview generation gösterilebilir. Atölye contract'ın koddan önce nasıl tartışılabileceğini somutlaştırır.

Pact Contract Testing Lab

İki takım consumer ve provider rollerini paylaşabilir. Consumer expectation hazırlarken provider bunu CI'de doğrular. Breaking response değişikliği bilinçli olarak uygulanıp test failure gözlemlenebilir. Ardından migration veya additive redesign yapılabilir. Bu çalışma cross-team dependency yönetimini pratik olarak öğretir.

V1 → V2 Migration Projesi

Topluluk içinde küçük bir servis önce v1 olarak yayınlanabilir. Daha sonra breaking requirements verilerek v2 tasarlanır. Client inventory, migration guide ve parallel run aşamaları uygulanabilir. Dashboard v1 adoption düşüşünü gösterir. Proje lifecycle'ın baştan sona deneyimlenmesini sağlar.

Açık Kaynak API Gateway Template'i

Template path ve header version routing, logging ve basic rate limiting içerebilir. Deprecation metadata merkezi configuration'dan yönetilebilir. Yeni projeler bu template üzerinden daha hızlı standardize olabilir. Test suite cache ve routing senaryolarını kapsayabilir. Community contribution modeli dokümantasyon ve örneklerle desteklenebilir.

OpenAPI Lint Rules Projesi

Topluluk ortak naming ve versioning kurallarını lint rule set'e dönüştürebilir. Removed field veya eksik description gibi durumlar otomatik uyarı üretebilir. Rule rationale dokümante edilmelidir. Farklı örnek API'ler üzerinde test yapılabilir. Bu proje API governance konusunu doğrudan kodlanabilir hale getirir.

Open Source API Tooling Contribution Day

Katılımcılar API tooling repository'lerinde documentation, test veya küçük feature katkıları üzerinde çalışabilir. Önceden uygun issue listesi hazırlanması başlangıcı kolaylaştırır. Pull request review süreci birlikte öğrenilebilir. Katılımcılar yalnızca araç kullanmak yerine ekosistemin nasıl geliştirildiğini de görür. Ortak çalışma sonraki topluluk projeleri için deneyim oluşturur.

Sık Sorulan Sorular

REST API versioning konusunda sorular genellikle teknik yöntem seçimi ile başlasa da kısa sürede compatibility, SDK ve lifecycle yönetimine uzanır. Aşağıdaki cevaplar sık karşılaşılan karar noktalarını pratik biçimde özetler. Tek bir yaklaşımın her API için geçerli olmadığı unutulmamalıdır. Client ownership ve release cycle çoğu kararı doğrudan etkiler. Özellikle kurumsal REST API versiyonlama ve entegrasyon danışmanlığı ihtiyaçlarında önce mevcut contract ve consumer envanterinin çıkarılması daha doğru karar verilmesini sağlar.

REST API versiyonlama nedir?

REST API versiyonlama farklı contract davranışlarının istemci tarafından açık biçimde seçilebilmesini sağlayan yöntemdir. Path, header, query veya tarih tabanlı modeller kullanılabilir. Asıl amaç breaking değişiklik yapıldığında mevcut client'ların aniden bozulmasını önlemektir. Versioning deprecation ve migration politikasıyla birlikte anlam kazanır. Her değişiklik için yeni version açmak gerekli değildir.

API versioning neden gereklidir?

API zaman içinde yeni ihtiyaçlar ve güvenlik gereksinimleri nedeniyle değişir. Bazı değişiklikler mevcut client koduyla uyumlu değildir. Versioning eski ve yeni contract'ı belirli süre paralel yaşatabilir. İstemciler kendi release takvimlerinde migrate olur. Bu yaklaşım ürün gelişimi ile entegrasyon istikrarı arasında denge kurar.

REST API için v1 URL'de mi header'da mı olmalıdır?

Her iki yöntem de doğru uygulanabilir. URL path daha görünür ve routing açısından basittir. Header URL'i sabit tutar ve contract seçimini metadata'ya taşır. Cache ve developer tooling kapasitesi karar üzerinde etkilidir. Organizasyon için tutarlı tek bir standart seçmek çoğu zaman yöntem tartışmasından daha değerlidir.

Header-based API versioning nasıl çalışır?

İstemci request içinde özel version header gönderir. Gateway veya server header değerine göre uygun contract handler'ı seçer. Sürüm log ve metric alanı olarak kaydedilebilir. Cache key version header'ı dikkate almalıdır. Default version davranışı açık biçimde tanımlanmalıdır.

Calendar versioning nedir?

Calendar versioning contract'ı major sayı yerine yayın tarihiyle tanımlar. Örneğin desteklenen bir tarih değeri request header'ında gönderilebilir. Bu model API'nin hangi dönem davranışının seçildiğini açıkça gösterir. Support window yine ayrıca tanımlanmalıdır. Eski tarihler deprecation ve sunset sürecinden geçebilir.

Semantic versioning REST API'lerde kullanılmalı mı?

Semantic Versioning SDK ve library paketlerinde oldukça faydalıdır. REST API contract için her minor veya patch değerini istemciye expose etmek her zaman gerekli değildir. API aynı major contract altında additive biçimde evolve edebilir. Major breaking boundary veya calendar version daha sade olabilir. Seçim API kullanım modeline göre yapılmalıdır.

Breaking change nedir?

Breaking change mevcut desteklenen client'ın değişiklik yapmadan çalışmaya devam edemediği contract farkıdır. Field removal, type change ve yeni required parameter açık örneklerdir. Status code veya authorization davranışı da breaking olabilir. Yapısal ve davranışsal etkiler birlikte değerlendirilmelidir. Yeni version veya compatibility migration gerekebilir.

Yeni response field eklemek breaking change midir?

Çoğu esnek JSON client için yeni optional response field additive değişikliktir. Ancak strict unknown-field validation kullanan client'lar hata verebilir. Generated SDK davranışı da önemlidir. Bu nedenle mutlak biçimde güvenli kabul edilmemelidir. Eski SDK ile yeni server compatibility testi en iyi doğrulamayı sağlar.

API backward compatibility nasıl korunur?

Optional fields, unknown field tolerance ve additive evolution temel yöntemlerdir. Breaking changes yeni version veya adapter ile ayrılabilir. Old SDK golden tests gerçek uyumluluğu doğrular. OpenAPI diff structural riskleri erken gösterir. Client usage telemetry hangi davranışların hâlâ production'da kullanıldığını anlamaya yardımcı olur.

API ile SDK version aynı olmak zorunda mıdır?

Hayır, API contract ve SDK package farklı yaşam döngülerine sahiptir. SDK bug fix API değişmeden yeni package version çıkarabilir. Aynı API v2 farklı SDK major sürümleri tarafından desteklenebilir. Compatibility matrix bu ilişkiyi açıklar. İsimlendirmede iki version türü net ayrılmalıdır.

OpenAPI breaking change nasıl tespit edilir?

Old ve new OpenAPI structural diff ile karşılaştırılabilir. Removed path, required parameter ve type changes otomatik rule set ile bulunur. CI pipeline breaking change olduğunda release'i durdurabilir. Behavioral değişiklikler için contract ve integration tests de gerekir. Human review semantic etkileri değerlendirmeyi tamamlar.

Consumer-driven contract testing nedir?

Consumer-driven contract testing istemcinin provider'dan beklediği davranışı contract olarak tanımlar. Provider bu expectation'ları kendi CI sürecinde doğrular. Breaking change consumer production'a çıkmadan fark edilebilir. Internal microservice ve partner entegrasyonlarında özellikle etkilidir. OpenAPI diff ile birlikte kullanıldığında daha geniş koruma sağlar.

Deprecation header nedir?

Deprecation header API response'unda resource veya operation'ın deprecated durumunu machine-readable biçimde iletebilir. SDK ve monitoring sistemleri bu sinyali kullanabilir. Deprecation removal anlamına gelmez. İstemci support window boyunca çalışmaya devam edebilir. Replacement ve migration guide ayrıca sunulmalıdır.

Sunset header nedir?

Sunset header resource'un gelecekte erişilemez hale gelmesinin beklendiği zamanı bildirir. Deprecation sinyalinden farklıdır. İstemci bu tarihi migration deadline planlamasında kullanabilir. Runtime warning documentation ve e-posta iletişimiyle desteklenmelidir. Tarih gelmeden critical client usage kontrol edilmelidir.

Deprecated API ne kadar süre desteklenmelidir?

Support süresi client release cycle ve API türüne göre değişir. Public veya mobile client'lar genellikle daha uzun migration window gerektirir. Internal API ekipleri doğrudan koordine edilebilir. En önemli nokta sürenin önceden açıkça tanımlanmasıdır. Security exception'ları ayrı policy altında yönetilmelidir.

Eski API version'ını kullanan client'lar nasıl bulunur?

Gateway loglarında version ve client ID birlikte tutulmalıdır. Request count ve last-seen active usage'ı gösterir. SDK version eklenirse migration riski daha iyi anlaşılır. Client inventory owner ve contact bilgisi sağlar. Dashboard sunset öncesinde kalan consumer'ları listeler.

API migration nasıl yapılır?

Önce breaking changes ve client inventory çıkarılır. V2 contract, SDK ve migration guide hazırlanır. Pilot, shadow veya parallel run ile yeni davranış doğrulanır. Client'lar cohort halinde migrate edilir. V1 usage yeterince düştüğünde deprecation, sunset ve removal tamamlanır.

Eski API kapatıldığında hangi HTTP status code dönmelidir?

Kalıcı olarak kaldırılmış eski endpoint için 410 Gone uygun senaryolarda açık bir lifecycle sinyali olabilir. Structured error body migration bilgisini taşıyabilir. Replacement endpoint veya documentation sunulmalıdır. Her API semantics'i ayrıca değerlendirilmelidir. Kapatma sonrasında remaining traffic monitoring devam etmelidir.

Mobil uygulamalarda API versioning nasıl yönetilir?

Mobil backend eski app version'ların uzun süre yaşayacağını varsaymalıdır. App version ve platform telemetry ile izlenebilir. Business code'a dağılmış version checks yerine capability mapping kullanılabilir. Minimum supported app version yalnızca gerektiğinde uygulanmalıdır. Migration window app store ve kullanıcı update davranışına göre planlanmalıdır.

API SDK'ları nasıl sürümlendirilmelidir?

SDK package'ları için Semantic Versioning doğal bir yöntemdir. Breaking public interface change major release gerektirir. API compatibility matrix hangi contract version'larla çalıştığını gösterir. EOL ve minimum runtime policy ayrıca yayınlanmalıdır. Generated SDK CI pipeline contract değişiklikleriyle senkron tutulmalıdır.

REST API Versiyonlama Stratejileri Hakkında Ek Sorular

Aşağıdaki sorular versioning yöntemini seçmekten migration desteğine kadar en sık karar verilen alanları kısa bir çerçevede toplar. Her cevap teknik seçimi istemci etkisiyle birlikte ele alır. Çünkü API'nin gerçek başarısı yalnızca server'ın yeni version'ı çalıştırmasıyla değil, consumer'ların sorunsuz geçebilmesiyle ölçülür. Kurumsal ekiplerde bu süreç governance, testing ve observability ile desteklendiğinde daha öngörülebilir hale gelir. Eğitim veya topluluk desteği arayan geliştiriciler de aynı prensipleri küçük proje ve atölyelerde uygulayarak deneyim kazanabilir.

REST API versiyonlama stratejileri nasıl uygulanır ve hangi yöntem tercih edilmelidir?

Önce breaking change tanımı ve client profili çıkarılmalıdır. Public ve çok sayıda third-party consumer bulunan API için görünür path veya explicit header gibi yöntemler güçlü seçeneklerdir. Internal API'de gateway ve contract testing altyapısına göre header veya capability yaklaşımı tercih edilebilir. Yöntem seçildikten sonra cache, routing, OpenAPI, SDK ve observability aynı version bilgisini kullanmalıdır. En doğru yöntem teknik olarak en gösterişli olan değil, ekiplerin uzun süre tutarlı uygulayabileceği ve istemcilerin kolay anlayabileceği yöntemdir.

URL path header query parameter ve media type tabanlı API versiyonlama yöntemleri arasındaki farklar nelerdir?

URL path versioning sürümü adres içinde görünür hale getirir ve routing ile cache yönetimini kolaylaştırır. Header versioning URL'i sabit tutar fakat cache key ve debugging için daha dikkatli altyapı gerekir. Query parameter manuel test açısından rahattır, ancak CDN query handling ayarları doğrulanmalıdır. Media type yaklaşımı HTTP content negotiation kavramıyla uyumludur fakat geliştirici deneyimi daha fazla tooling desteği isteyebilir. Karar verirken yalnızca URL görünümüne değil, gateway, cache, SDK ve target developer kitlesine birlikte bakılmalıdır.

REST API sürüm değişikliklerinde geriye dönük uyumluluk (Backward Compatibility) nasıl korunur?

Backward compatibility için additive evolution, optional field ve unknown field tolerance temel tasarım araçlarıdır. Breaking değişiklikler yeni major contract veya compatibility adapter ile ayrılabilir. Old SDK ile new server golden tests gerçek istemci davranışını doğrular. OpenAPI diff yapısal riskleri, consumer contract testing ise kullanılan davranışları erken yakalar. Production usage telemetry de dokümante edilmemiş bağımlılıkların ve eski client'ların görünür olmasını sağlar.

Eski API sürümlerini kullanan istemciler için versiyon geçişi deprecation ve sunset süreçleri nasıl yönetilmelidir?

Önce replacement production kalitesinde hazır olmalı ve migration guide yayınlanmalıdır. Ardından eski version deprecated ilan edilerek runtime header, changelog ve doğrudan client notification devreye alınmalıdır. Client ID, request count ve last-seen üzerinden migration ilerlemesi izlenmelidir. Sunset tarihi yaklaşınca kritik consumer, support ticket ve traffic share için readiness gate çalıştırılmalıdır. Kriterler sağlandığında eski route kaldırılır, structured error ve migration dokümantasyonu belirli süre daha erişilebilir tutulur.

REST API versiyonlama ve istemci yönetimi konusunda yakınımda danışmanlık veya eğitim nerede bulabilirim?

Diyarbakır'da API tasarımı, backend geliştirme, açık kaynak çalışmaları ve topluluk etkinlikleriyle pratik deneyim kazanmak isteyen geliştiriciler Diyarbakır Yazılım Topluluğu çalışmalarını inceleyebilir. Topluluk hakkında bilgi almak için https://www.diyarbakiryazilim.com.tr/about adresi kullanılabilir. Proje ve uygulama odaklı çalışmalar için https://www.diyarbakiryazilim.com.tr/projects sayfası iyi bir başlangıç noktasıdır. REST API geliştirme ve backend danışmanlığı yakınımda şeklinde araştırma yapan ekipler için de önce ihtiyaç, mevcut contract yapısı ve migration risklerinin birlikte değerlendirilmesi doğru yaklaşımı belirlemeyi kolaylaştırır. Eğitim tarafında ise küçük bir v1-v2 migration projesi, OpenAPI diff ve contract testing çalışması gerçek production senaryolarına hazırlanmak için güçlü bir öğrenme modeli sunar.

Sonuç

REST API Versiyonlama Stratejileri ve İstemci Yönetimi, API'nin URL'sine bir sürüm numarası eklemekten çok daha geniş bir mühendislik disiplinidir. Sağlam bir yaklaşım contract tasarımını, backward compatibility kararlarını, OpenAPI otomasyonunu, SDK yaşam döngüsünü, istemci envanterini, deprecation iletişimini ve sunset kriterlerini tek bir süreçte birleştirir. On yıllık backend pratiğinde tekrar tekrar gördüğüm ortak ders şudur: en rahat migration, breaking change ortaya çıktıktan sonra aceleyle hazırlanan değil, ilk API sözleşmesi tasarlanırken gelecekteki değişim düşünülerek hazırlanan migration'dır. Kendi API'nizde v1 ve v2 geçişi tasarlıyor, contract testing öğrenmek veya ekip içinde gerçek bir migration projesi geliştirmek istiyorsanız Diyarbakır Yazılım Topluluğu'nun çalışmalarına https://www.diyarbakiryazilim.com.tr üzerinden ulaşabilirsiniz. Doğru versioning policy, iyi telemetry ve açık client iletişimi birlikte kullanıldığında API hem gelişmeye devam eder hem de onu kullanan uygulamalar için daha öngörülebilir bir platform haline gelir.