Kısaca
URL versiyonlama (/v1/pets) çoğu ekip için en pratik API versiyonlama stratejisidir. Görünürdür, önbelleğe alınabilir ve test etmesi kolaydır. Başlık versiyonlama ve içerik uzlaşması daha "saf" REST'tir ancak karmaşıklık katar. Modern PetstoreAPI, semantik versiyonlama ve açık sonlandırma politikaları ile URL versiyonlamayı kullanır.
Giriş
API'nızın bozucu bir değişikliğe ihtiyacı var. /pets için yanıt formatını basit bir diziden, sayfalama meta verileri içeren sarılmış bir nesneye değiştiriyorsunuz. Mevcut istemciler bozulacak. Ne yaparsınız?
API versiyonlamaya ihtiyacınız var. Ama hangi strateji? URL versiyonlama (/v1/pets mi yoksa /v2/pets mi)? Başlık versiyonlama (Accept: application/vnd.petstore.v1+json)? İçerik uzlaşması? Her yaklaşımın tutkulu savunucuları ve güçlü görüşleri var.
Cevap: URL versiyonlama çoğu ekip için kazanır. Pragmatiktir, görünürdür ve tüm HTTP araçlarıyla çalışır. Başlık versiyonlama ve içerik uzlaşması teorik olarak daha temizdir ancak çoğu ekibin ihtiyaç duymadığı bir karmaşıklık katar.
Modern PetstoreAPI, semantik versiyonlama ve açık sonlandırma politikaları ile URL versiyonlamayı kullanır. Mevcut versiyon v1 olup, v2 gelecekteki bozucu değişiklikler için planlanmıştır.
Bu rehberde, üç ana versiyonlama stratejisini, avantaj ve dezavantajlarını ve Modern PetstoreAPI'yi referans alarak versiyonlamayı doğru şekilde nasıl uygulayacağınızı öğreneceksiniz.
API'ler Neden Versiyonlamaya İhtiyaç Duyar?
API'lar evrilir. Özellikler eklersiniz, hataları düzeltirsiniz ve tasarımları iyileştirirsiniz. Bazen bu değişiklikler mevcut istemcileri bozar.
Bozucu Değişiklikler
Mevcut istemcileri bozan değişiklikler:
1. Alanları kaldırma:
// v1
{"id": "123", "name": "Fluffy", "age": 3}
// v2 (bozucu: yaş kaldırıldı)
{"id": "123", "name": "Fluffy"}
2. Alan türlerini değiştirme:
// v1
{"price": "19.99"}
// v2 (bozucu: string'den sayıya)
{"price": 19.99}
3. Yanıt yapısını değiştirme:
// v1 (basit dizi)
[{"id": "123"}]
// v2 (bozucu: sarılmış nesne)
{"data": [{"id": "123"}], "pagination": {...}}
4. URL yapısını değiştirme:
// v1
GET /pet/123
// v2 (bozucu: çoğul)
GET /pets/123
5. Kimlik doğrulamayı değiştirme:
// v1: sorguda API anahtarı
GET /pets?api_key=xxx
// v2 (bozucu: Taşıyıcı token)
GET /pets
Authorization: Bearer xxx
Bozucu Olmayan Değişiklikler
İstemcileri bozmayan değişiklikler:
- Yeni uç noktalar ekleme
- İsteklere isteğe bağlı alanlar ekleme
- Yanıtlara yeni alanlar ekleme (istemciler bilinmeyen alanları göz ardı etmelidir)
- Yeni sorgu parametreleri ekleme
- Mevcut kaynaklara yeni HTTP metodları ekleme
Versiyonlama Kararı
Bozucu bir değişikliğe ihtiyaç duyduğunuzda iki seçeneğiniz vardır:
1. Tüm istemcileri yükseltmeye zorlamak - Basit ama mevcut entegrasyonları bozar
2. Birden fazla sürümü desteklemek - Daha fazla iş ama geriye dönük uyumluluğu korur
Çoğu genel API 2. seçeneği tercih eder. Versiyonlama, API'yi geliştirirken istemcilere geçiş için zaman tanır.
URL Versiyonlama
URL versiyonlama, versiyon numarasını URL yoluna koyar.
Nasıl Çalışır
GET /v1/pets
GET /v2/pets
Versiyon, kaynak tanımlayıcının bir parçasıdır. Farklı versiyonlar farklı kaynaklardır.
Artıları
1. Görünür ve açık
Versiyon URL'dedir. Günlüklerde, tarayıcı geçmişinde ve belgelerde görebilirsiniz. Hatırlanacak gizli başlıklar yoktur.
2. Test etmesi kolay
curl https://petstoreapi.com/v1/pets
curl https://petstoreapi.com/v2/pets
Her iki versiyonu da basit HTTP istekleriyle test edebilirsiniz.
3. Tüm HTTP araçlarıyla çalışır
Tarayıcılar, önbellekler, proxy'ler ve yük dengeleyiciler farklı URL'ler görür. Her versiyonu bağımsız olarak yönlendirebilir, önbelleğe alabilir ve günlüğe kaydedebilirler.
4. İstemciler için basit
İstemciler sadece URL'yi değiştirir. Özel başlıklar veya içerik uzlaşma mantığı yoktur.
5. Sonlandırması kolay
/v1 uç noktalarını /v2'yi etkilemeden kaldırabilirsiniz.
Eksileri
1. "Saf" REST değil
REST püristleri, /v1/pets/123 ve /v2/pets/123'ün aynı kaynak olduğunu, bu yüzden aynı URL'ye sahip olmaları gerektiğini savunur. Versiyon başlıkta veya içerik uzlaşmasında olmalıdır.
2. URL kirliliği
API'nızın birden fazla URL alanı vardır: /v1/*, /v2/* vb.
3. Bireysel kaynakları versiyonlamak daha zor
Sadece bir uç noktayı versiyonlamak isterseniz, tüm API'yi versiyonlamanız veya tutarsızlık yaratmanız gerekir.
Uygulama
URL'de ana versiyon:
/v1/pets
/v2/pets
Alt versiyonları dahil etmeyin:
❌ /v1.2/pets (çok ayrıntılı)
✅ /v1/pets (sadece ana versiyon)
Dahili olarak semantik versiyonlama kullanın:
- v1.0.0 - İlk sürüm
- v1.1.0 - Yeni alanlar ekleme (bozucu olmayan)
- v1.2.0 - Yeni uç noktalar ekleme (bozucu olmayan)
- v2.0.0 - Bozucu değişiklikler (yeni URL: /v2)
Modern PetstoreAPI, mevcut versiyon olarak /v1 ile URL versiyonlamayı kullanır.
Başlık Versiyonlama
Başlık versiyonlama, versiyonu özel bir HTTP başlığına koyar.
Nasıl Çalışır
GET /pets
API-Version: 1
GET /pets
API-Version: 2
URL aynı kalır. Başlık versiyonu belirtir.
Artıları
1. Temiz URL'ler
/pets tüm versiyonlar için aynıdır. /v1 veya /v2 öneki yoktur.
2. Daha "RESTful"
Kaynak tanımlayıcı (/pets/123) değişmez. Temsil, başlığa göre değişir.
3. Ayrıntılı versiyonlama
Bireysel kaynakları versiyonlayabilirsiniz:
GET /pets
API-Version: 2
GET /orders
API-Version: 1
Eksileri
1. Görünmez
Versiyon URL'de değildir. Günlüklerde veya tarayıcı geçmişinde başlıkları kontrol etmeden göremezsiniz.
2. Test etmesi daha zor
curl -H "API-Version: 1" https://petstoreapi.com/pets
curl -H "API-Version: 2" https://petstoreapi.com/pets
Başlığı dahil etmeyi hatırlamanız gerekir.
3. Önbellekleme karmaşıklığı
Önbellekler API-Version başlığını dikkate almalıdır. Yanıtlarda Vary: API-Version'a ihtiyacınız vardır.
4. İstemci karmaşıklığı
İstemcilerin özel başlık mantığına ihtiyacı vardır. Tüm HTTP istemcileri bunu kolaylaştırmaz.
5. Varsayılan versiyon belirsizliği
İstemci başlığı göndermezse ne olur? Varsayılan bir değere ihtiyacınız vardır, bu da örtük davranış yaratır.
Uygulama
Özel başlık:
API-Version: 1
Veya Accept başlığını kullanın:
Accept: application/vnd.petstore.v1+json
Vary başlığını dahil edin:
Vary: API-Version
Bu, önbelleklerin önbelleğe alırken başlığı dikkate almasını söyler.
İçerik Uzlaşması
İçerik uzlaşması, Accept başlığını özel medya türleriyle kullanır.
Nasıl Çalışır
GET /pets
Accept: application/vnd.petstore.v1+json
GET /pets
Accept: application/vnd.petstore.v2+json
Versiyon medya türünün bir parçasıdır.
Artıları
1. En "RESTful"
REST böyle tasarlandı. Aynı kaynağın farklı temsilleri.
2. HTTP standartlarına uyar
Standart HTTP içerik uzlaşmasını kullanır.
3. Birden fazla formatı destekler
Aynı anda versiyonlama ve formatlama yapabilirsiniz:
Accept: application/vnd.petstore.v1+json
Accept: application/vnd.petstore.v1+xml
Eksileri
1. Karmaşık
İstemciler medya türlerini ve içerik uzlaşmasını anlamalıdır.
2. Test etmesi daha zor
curl -H "Accept: application/vnd.petstore.v1+json" https://petstoreapi.com/pets
3. Zayıf araç desteği
Birçok HTTP istemcisi ve aracı özel medya türlerini iyi işleyemez.
4. Önbellekleme karmaşıklığı
Önbellekler Accept başlığını dikkate almalıdır. Vary: Accept'e ihtiyacınız vardır.
5. Çoğu API için gereksiz
Çoğu API bu düzeyde bir karmaşıklığa ihtiyaç duymaz.
Uygulama
Satıcıya özgü medya türü:
Accept: application/vnd.petstore.v1+json
Yanıt:
Content-Type: application/vnd.petstore.v1+json
Vary: Accept
Modern PetstoreAPI Versiyonlamayı Nasıl Uygular?
Modern PetstoreAPI, açık politikalarla URL versiyonlamayı kullanır.
Mevcut Versiyon: v1
https://petstoreapi.com/v1/pets
https://petstoreapi.com/v1/orders
https://petstoreapi.com/v1/users
Tüm uç noktalar /v1 altındadır.
Versiyon Yanıt Başlığı
Her yanıt API versiyonunu içerir:
X-API-Version: 1.2.0
Bu, URL yalnızca ana versiyonu gösterse bile tam versiyonu (ana.alt.yama) gösterir.
Sonlandırma Uyarıları
Bir versiyon sonlandırıldığında, yanıtlar şunları içerir:
Deprecation: true
Sunset: Sat, 31 Dec 2026 23:59:59 GMT
Link: <https://docs.petstoreapi.com/migration/v1-to-v2>; rel="deprecation"
Deprecation- Versiyonun sonlandırıldığını belirtirSunset- Versiyonun ne zaman kaldırılacağını belirtirLink- Geçiş rehberi
Versiyon Keşfi
Kök uç nokta mevcut versiyonları listeler:
GET https://petstoreapi.com/
{
"versions": [
{
"version": "v1",
"status": "current",
"docsUrl": "https://docs.petstoreapi.com/v1"
}
]
}
Semantik Versiyonlama
Modern PetstoreAPI dahili olarak semantik versiyonlamayı takip eder:
- Ana (v1, v2) - Bozucu değişiklikler, yeni URL
- Alt (v1.1, v1.2) - Yeni özellikler, geriye dönük uyumlu
- Yama (v1.1.1, v1.1.2) - Hata düzeltmeleri, geriye dönük uyumlu
Yalnızca ana versiyonlar URL'lerde görünür.
Apidog ile API Versiyonlarını Test Etme
Apidog, birden fazla API versiyonunu test etmenize yardımcı olur.
Birden Fazla Versiyonu İçe Aktarma
Her versiyon için OpenAPI spesifikasyonlarını içe aktarın:
petstore-v1.yaml → Ortam: v1
petstore-v2.yaml → Ortam: v2
Tüm Versiyonlara Karşı Testleri Çalıştırma
Her iki versiyona karşı çalışan test paketleri oluşturun:
// v1'i test et
pm.environment.set("baseUrl", "https://petstoreapi.com/v1");
pm.sendRequest(pm.environment.get("baseUrl") + "/pets");
// v2'yi test et
pm.environment.set("baseUrl", "https://petstoreapi.com/v2");
pm.sendRequest(pm.environment.get("baseUrl") + "/pets");
Versiyona Özgü Davranışı Doğrulama
v1 ve v2'nin farklı davrandığını test edin:
// v1 basit dizi döndürür
pm.test("v1 dizi döndürür", function() {
pm.expect(pm.response.json()).to.be.an('array');
});
// v2 sarılmış nesne döndürür
pm.test("v2 sarılmış nesne döndürür", function() {
pm.expect(pm.response.json()).to.have.property('data');
pm.expect(pm.response.json()).to.have.property('pagination');
});
Sonlandırma Başlıklarını Kontrol Etme
Sonlandırılmış versiyonların uygun başlıkları içerdiğini test edin:
pm.test("Sonlandırılan versiyon başlıkları içerir", function() {
pm.response.to.have.header("Deprecation");
pm.response.to.have.header("Sunset");
});
Versiyon Sonlandırma Stratejisi
Eski versiyonları istemcileri bozmadan nasıl sonlandırılır.
1. Sonlandırmayı Erken Duyurun
Müşterilere en az 6-12 ay önceden bildirimde bulunun:
Deprecation: true
Sunset: Sat, 31 Dec 2026 23:59:59 GMT
2. Geçiş Rehberi Sağlayın
Tüm bozucu değişiklikleri ve nasıl geçiş yapılacağını belgeleyin:
Link: <https://docs.petstoreapi.com/migration/v1-to-v2>; rel="deprecation"
3. Kullanımı İzleyin
Hangi istemcilerin hala sonlandırılan versiyonları kullandığını takip edin:
X-API-Version: 1.2.0
X-Client-ID: abc123
Gerekirse doğrudan istemcilerle iletişime geçin.
4. Aşamalı Kapatma
Versiyonu hemen kaldırmayın:
- 1-6. Ay: Sonlandırmayı duyurun
- 7-9. Ay: Sonlandırma başlıkları ekleyin
- 10-11. Ay: Sonlandırılan versiyon için hız limitlerini azaltın
- 12. Ay: Sonlandırılan versiyonu kaldırın
5. Belgeleri Saklayın
Kaldırıldıktan sonra bile, eski versiyonun belgelerini saklayın. İstemcilerin bunlara başvurması gerekebilir.
Sonuç
URL versiyonlama, çoğu ekip için en pratik API versiyonlama stratejisidir. Görünürdür, test etmesi kolaydır ve tüm HTTP araçlarıyla çalışır. Başlık versiyonlama ve içerik uzlaşması daha "saf" REST'tir ancak karmaşıklık katar.
Modern PetstoreAPI, mevcut versiyon olarak /v1 ile URL versiyonlamayı, dahili olarak semantik versiyonlamayı ve açık sonlandırma politikalarını kullanır. Bu yaklaşım, pragmatizmi iyi API tasarımıyla dengeler.
Birden fazla API versiyonunu test etmek, versiyona özgü davranışı doğrulamak ve versiyonlar arasında sorunsuz geçişler sağlamak için Apidog'u kullanın.
SSS
URL versiyonlama mı yoksa başlık versiyonlama mı kullanmalıyım?
Özel bir nedeniniz yoksa URL versiyonlama kullanın. Daha basittir, daha görünürdür ve test etmesi daha kolaydır. Başlık versiyonlama daha "RESTful"dur ancak çoğu ekibin ihtiyaç duymadığı bir karmaşıklık katar.
Aynı anda kaç versiyonu desteklemeliyim?
Maksimum 2 versiyonu destekleyin: mevcut ve önceki. Daha fazlasını desteklemek bakım yükü yaratır. İstemcilere geçiş için 6-12 ay verin, ardından eski versiyonları kaldırın.
v0'dan mı yoksa v1'den mi versiyonlamalıyım?
v1 ile başlayın. v0 kararsızlık anlamına gelir. API'nız v1 için yeterince stabil değilse, henüz herkese açık olarak yayınlamayın.
Her uç noktayı versiyonlamam gerekiyor mu?
Hayır. Yalnızca bozucu değişiklikler yaptığınızda versiyonlayın. Mevcut uç noktaları değiştirmeden yenilerini eklerseniz, yeni bir versiyona ihtiyacınız olmaz.
URL'lerdeki alt versiyonlar ne olacak?
URL'lere alt versiyonları dahil etmeyin. /v1.2 yerine /v1 kullanın. Alt versiyonlar geriye dönük uyumludur, bu nedenle istemcilerin URL'leri değiştirmesine gerek yoktur.
Versiyona özgü hataları nasıl ele alırım?
Desteklenen tüm versiyonlardaki hataları düzeltin. Bir hata yalnızca v1'de mevcutsa, onu v1'de düzeltin. İstemcileri hata düzeltmeleri için v2'ye yükseltmeye zorlamayın.
Semantik versiyonlama kullanmalı mıyım?
Evet, dahili olarak. Ana.alt.yama versiyonlarını takip edin, ancak URL'lerde yalnızca ana versiyonları gösterin. Bu, bozucu olmayan değişiklikler için size esneklik sağlar.
Sadece bir uç noktayı versiyonlamam gerekirse ne olur?
URL versiyonlama ile, tüm API'yi versiyonlamanız veya tutarsızlık yaratmanız gerekir. Bu bir ödünleşimdir. Çoğu ekip basitlik adına tüm API'yi versiyonlamayı kabul eder.