1. GİRİŞ

API'ler (Application Programming Interfaces) modern yazılımın merkezindedir. Bir ürünün büyüdükçe API'leri evrimleşir; yeni özellikler eklenir, veri modelleri değişir ve performans iyileştirmeleri yapılır. Bu değişimler sırasında API tüketicilerinin (mobil uygulamalar, üçüncü parti entegrasyonlar, mikroservisler) kırılmaması için versiyonlama stratejileri kritik öneme sahiptir. API versiyonlama, hem geliştirici deneyimini (DX) hem de işletme sürdürülebilirliğini doğrudan etkiler.

Bu konu neden bugün önemli?

• API tüketimi ve entegrasyon sayısı arttı; backward compatibility ihlalleri müşteri deneyimini bozuyor.
• Microservices, API‑first ve third‑party ekosistemleri versiyonlama ihtiyacını artırdı.
• DevOps ve CI/CD süreçleriyle birlikte hızlı ve güvenli sürüm geçişleri planlamak gerekiyor.

Kimler için önemli?

• API tasarımcıları, backend geliştiriciler ve yazılım mimarları
• Platform mühendisleri, SRE ve API gateway yöneticileri
• Ürün ekipleri ve entegrasyon partnerleri

Hangi problemleri çözüyor?

• Tüketicileri kırmadan yeni özellik sunma (backward compatibility)
• Uzun dönemli bakım, deprecation ve tüketici göçünü yönetme
• Contract testing ve sürüm uyumluluğu ile güvenli deploy sağlama

2. KAVRAMSAL TEMELLER

2.1 Versiyonlama nedir?

Versiyonlama, API'nin değişikliklerini tüketicilere uygun şekilde duyurmak ve aynı zamanda geriye dönük uyumluluğu yönetmek için kullanılan yöntemlerin bütünüdür. Versiyonlama; hem teknik (URI, header, medya tipi) hem de süreçsel (deprecation politikası, migration planları) boyutları içerir.

2.2 Temel terimler

• Backward compatibility (geriye dönük uyumluluk): Yeni sürümün eski tüketicileri kırmaması.
• Breaking change: Tüketicinin mevcut davranışını etkileyen değişiklik (ör. required alan ekleme, alan kaldırma).
• Deprecation: Eski API yüzeyinin kullanımdan kaldırılması süreci; migrate yönergeleri ve zaman çizelgesi içerir.
• Semantic Versioning (SemVer): Major.Minor.Patch biçiminde sürüm numaralandırma; breaking changes major sürüme yansır.
• Contract: API sözleşmesi; OpenAPI/Swagger, AsyncAPI veya Protobuf gibi tanımlamaları kapsar.

2.3 Sürüm yönetiminin bileşenleri

• Sürüm ortaya koyma metodu (URI/header/content negotiation)
• Contract definition ve contract testing (consumer-driven contracts)
• Deprecation ve migration politikaları
• Dokümantasyon, SDK üretimi ve changelog

3. NASIL ÇALIŞIR? — STRATEJİLERİN TEKNİK DETAYLARI

3.1 URI (path) versiyonlama

URI versiyonlama en yaygın ve en görünür yaklaşımlardan biridir. Örnek: /v1/customers veya /api/v2/orders. Avantajları basitlik, kolay router yapılandırması ve açık sürüm görünürlüğüdür. Dezavantajı ise URL'lerin sürüm bilgisiyle kirlenmesi ve bazı durumlarda kaynak kimliğinin belirsizleşmesidir.

3.2 Header versiyonlama

Header versiyonlama, Accept veya özel header (ör. X-API-Version) ile yapılır. Örnek: Accept: application/vnd.myapi.v2+json. Bu yaklaşım REST semantiklerine daha uygundur ve URL'leri temiz tutar. Ancak cache ve CDN davranışı ile uyum sorunları olabilir; ayrıca gateway/clients tarafında header yönetimi gerektirir.

3.3 Content negotiation (medya tipi) versiyonlama

Medya tipi versiyonlama, Accept header içinde versioned media types kullanır. Örnek: application/vnd.mycompany.resource+json; version=2. Bu yöntem API evriminde güçlü bir kontrol sunar, ancak karmaşıklaştırır ve istemci tarafı kütüphanelerin desteklenmesini gerektirir.

3.4 Query parametre ile versiyonlama

Versiyon bilgisi sorgu parametresi ile verilebilir: /customers?version=2. Basit uygulamalar için işe yarasa da cache politikasını ve analytics'i karmaşık hale getirebilir. Genelde önerilmez ama bazı durumlarda hızlı A/B testleri için tercih edilebilir.

3.5 No-version (evolutionary) yaklaşımı

Versiyon numarası kullanmamak ve API yüzeyini geriye dönük uyumlu tutarak evrimleştirmek diğer bir yaklaşımdır. Bu yaklaşım; tolerant reader (istemci toleransı), additive changes (yeni alan ekleme) ve deprecation metadata'sı ile mümkündür. Faydası URL'lerin temiz kalması ve sürüm yönetimi overhead'inin azalmasıdır. Dezavantajı, karmaşık breaking change'lerin yönetilmesinin zorlaşmasıdır.

3.6 gRPC / Protobuf versiyonlama

Binary protokoller ve Protobuf kullanıldığında mesaj alanlarını numaralandırmak, field addition/renumbering konusunda dikkat gerektirir. Protobuf geri uyumlu değişiklikleri destekleyecek şekilde tasarlanmıştır; ancak field silme veya renumbering breaking change sayılır. Semantic versioning ile paralel yürütülmelidir.

3.7 Semantic Versioning ve sürümleme politikaları

SemVer (MAJOR.MINOR.PATCH) API versiyonlama ile uyarlanabilir. Breaking change'ler major sürüme yükseltmeyi tetikler. Minor sürümler yeni geri uyumlu özellikleri, patch sürümler bugfix'leri gösterir. SemVer tüketiciler için net beklenti sağlar ancak API yüzeyinin küçük değişikliklerinde sürüm yönetimi disiplin ister.

4. GERÇEK DÜNYA KULLANIMLARI

4.1 Stripe — idempotency ve geriye dönük uyumluluk

Stripe örneğinde API'ler uzun dönemli istikrar ve güvenilirlik üzerine kuruludur. Deprecation politikasını açık biçimde duyurur, idempotency ve tracing mekanizmaları ile yanlış faturalamaları önler. Sürüm değişiklikleri dikkatle planlanır ve SDK'lar ile tüketicilere sunulur.

4.2 GitHub — header ve media type kullanımı

GitHub API'si uzun yıllar URI versiyonlama yerine medya tipi ve header tabanlı feature preview'ler kullanmıştır. Bu yaklaşım yeni özellikleri beta olarak sunmaya ve tüketicileri yavaşça göçe zorlamaya uygundur. Breaking change gerektiren durumlar nadiren yayınlanır.

4.3 Google APIs — protobuf, gRPC ve SemVer kombinasyonu

Google, gRPC ve Protobuf ile yüksek performanslı servisler sunar. Protobuf field yönetimi ve semantic versioning ile birlikte sıkı contract kuralları kullanılır. Client ve server tarafı kod jenerasyonu ile uyumluluk sağlanır.

4.4 Netflix — tolerant design ve client resilience

Netflix, microservices ekosisteminde tolerant reader ve producer yaklaşımını benimser. Client tarafında circuit breaker, fallback ve version tolerant parsers ile hizmet sürekliliği sağlanır. API evrimi ve feature rollout'lar progressive delivery ile kademeli olarak yapılır.

5. AVANTAJLAR VE SINIRLAMALAR

Avantajlar

• Güçlü versiyonlama ve deprecation politikaları, tüketiciyi korur ve güven sağlar.
• SemVer ve contract testing ile uyumluluk otomatikleştirilebilir.
• Header veya media type versiyonlama URL temizliği ve REST semantiklerine uygunluk sağlar.

Sınırlamalar

• URI versiyonlama URL karmaşası yaratabilir ve cache davranışını etkileyebilir.
• Header/media type versiyonlama CDN ve caching ile uyumsuzluk getirebilir.
• SemVer disiplini gerektirir; küçük ekiplerde sürüm kontrolü zorlayıcı olabilir.

6. ALTERNATİFLER VE KARŞILAŞTIRMA

7. EN İYİ PRATİKLER

Production kullanımı

• API sözleşmesini (OpenAPI/Protobuf/AsyncAPI) tek kaynak olarak saklayın ve CI ile doğrulayın.
• Consumer‑driven contract testing (Pact, Spring Cloud Contract) ile breaking change'leri erkenden tespit edin.
• Deprecation politikası oluşturun: duyuru, geriye dönük destek süresi, migration rehberi ve analytics ile takip.

Performans ve caching

• Header tabanlı versiyonlama kullanıyorsanız cache‑key stratejilerini gateway/edge üzerinde doğru yapılandırın.
• API gateway üzerinde version routing, request/response transformation ve canary deploy destekleri uygulayın.

Güvenlik

• Sürüm değişikliklerini authentication/authorization politika değişiklikleri ile yavaşça uygulayın; backward compatibility'yi bozmamaya özen gösterin.
• Deprecate edilen sürümlerde de güvenlik yamalarını uygulamaya devam edin; tüketicileri zorlayarak hızlıca eski sürümü kesmeyin.

Organizasyonel pratikler

• Changelog ve migration rehberi hazırlayın; SDK'lar ve örnek kodlar ile migration sürecini kolaylaştırın.
• Önem derecesi olan müşteriler için özel göç planları hazırlayın (premium support, dedicated migration assistance).

8. SIK YAPILAN HATALAR

• Versiyonlama stratejisini sonradan düşünmek—erken karar verilmeli ve dokümante edilmelidir.
• Deprecation sürecini belirsiz bırakmak—tüketiciler için net zaman ve rehber yoksa güven zedelenir.
• Contract testing'i atlamak—breaking change'ler yalnızca runtime'da değil, integration aşamasında tespit edilmelidir.
• URL'leri sık değiştirmek—URI stabilitesi tüketici güveni içindir.

9. GELECEK TRENDLER

1. Automated impact analysis: AI destekli araçlar API değişikliklerinin etkisini kod tabanı ve tüketiciler üzerinde analiz edecek.
2. Contract AI assistants: API sözleşmelerini analiz edip migration scriptleri, patch önerileri üreten yardımcılar yaygınlaşacak.
3. Standardized version metadata: CloudEvents ve OpenAPI içinde sürüm metadata standardı daha olgun hale gelecek.
4. Progressive delivery for APIs: Canary, feature flag ve traffic steering ile sürüm rollout'u daha sofistike olacak.

EK BÖLÜMLER

Sık Sorulan Sorular (FAQ)

1. 1. Hangi versiyonlama stratejisini seçmeliyim?

   İhtiyaca göre. Basit ve görünür olması isteniyorsa URI versiyonlama uygundur. URL temizliği ve REST semantiği öncelikliyse header/media type versiyonlama tercih edilebilir. Büyük ölçekli sistemlerde contract testing ve SemVer disiplinli uygulanmalıdır.

2. 2. SemVer API'lerde nasıl uygulanır?

   Breaking change'ler major sürüme, yeni geri uyumlu özellikler minor sürüme, bugfix'ler patch sürüme yansıtılır. SemVer'i API changelog ve SDK sürümlerine paralel yönetmek önemlidir.

3. 3. Deprecation süresi ne kadar olmalı?

   Sektöre ve müşteri ihtiyaçlarına göre değişir. Genelde 3–6 ay minimal, kurumsal müşteriler için 6–12 ay veya daha uzun periyotlar tercih edilebilir. Migration rehberi ve analytics ile süreci takip edin.

4. 4. URI versiyonlama cache sorunlarına neden olur mu?

   URI versiyonlama cache ile uyumludur (farklı URL farklı cache entries). Asıl sorun header tabanlı yaklaşımlarda CDN/edge cache key yönetiminden kaynaklanır.

5. 5. gRPC ile versiyon yönetiminde nelere dikkat etmeliyim?

   Protobuf field numaralandırmasına dikkat edin; alanları yeniden numaralandırmak veya silmek breaking change yaratır. Yeni alan eklemek genelde güvenlidir ama client/server codegen süreçleri koordine edilmelidir.

6. 6. No‑version stratejisi güvenli midir?

   No‑version (evolutionary) stratejisi mümkün fakat sıkı contract testing, tolerant parsing ve additive changes disiplinine ihtiyaç duyar. Büyük, heterojen tüketici tabanlarında riskli olabilir.

7. 7. Contract testing neden önemli?

   Contract testing, tüketici ve sağlayıcı arasındaki beklentilerin uyumunu teyit eder; breaking change'lerin erken aşamada tespit edilmesini sağlar. Consumer‑driven contract yaklaşımları entegrasyon riskini azaltır.

8. 8. Versiyonlama politikası nasıl dokümante edilir?

   API portal'ında versioning policy, deprecation timelines, migration guides, changelogs ve SDK upgrade rehberleri açık ve bulunabilir şekilde yer almalıdır.

Anahtar Kavramlar

Breaking change

Mevcut tüketicinin beklentisini bozan değişiklik.

Deprecation

Eski yüzeyin kaldırılacağına dair plan ve iletişim süreci.

SemVer

Semantic Versioning: major.minor.patch formatı ile sürümleme disiplini.

Contract testing

Provider ve consumer arasındaki sözleşmenin doğrulanması.

Media type versioning

Accept/Content‑Type header ile sürüm bilgisinin taşınması.

Öğrenme Yol Haritası

1. 0–1 ay: REST ve HTTP semantiklerini öğrenin; basit URI versiyonlama ile deneyim kazanın.
2. 1–3 ay: OpenAPI/Protobuf tanımları oluşturun; contract testing (Pact vb.) deneyin ve deprecation workflow kurun.
3. 3–6 ay: Header/media type versiyonlama, CDN cache key yönetimi ve progressive rollout tekniklerini uygulamalı olarak öğrenin.
4. 6–12 ay: SemVer disiplinini, gRPC/Protobuf versiyonlama nüanslarını ve AI destekli impact analysis araçlarını entegre edin.