Yeni bir sürüm açmadan API'mi geriye dönük uyumlu biçimde nasıl geliştirebilirim?

Kısa cevap: Değişikliklerinizin çoğunu yeni sürüm açmadan yapabilirsiniz — kural basit: ekleyin, asla silmeyin/yeniden adlandırmayın/tip değiştirmeyin ve istemcinin bilinmeyen alanları yok saydığına (tolerant reader) güvenin.

Kısa cevap

Kaçınılmaz kırıcı değişiklik içinse URL değil, header ile versiyon pin’leyin.

Neden

1. Kural bir: ekle, asla kaldırma veya yeniden amaçlandırma. Yanıta yeni bir alan eklemek geriye uyumludur; eski istemci onu görmezden gelir. Kırıcı olan hareket var olan bir alanı silmek, yeniden adlandırmak veya tipini/anlamını değiştirmektir (örneğin string iken object yapmak).

Ne yapmalı

1. Tolerant reader varsayımını doğrulayın. Birçok JSON parser bilinmeyen alanı yok sayar, ama strict schema validation yapan bir istemci (ya da bir kod-üretici DTO) yeni alanda patlayabilir. Mobil istemcinizin bunu gerçekten yaptığını bir eski build ile test edin; varsayıp geçmeyin.

2. Yeni request alanları optional + güvenli default olsun. Eski istemci yeni alanı hiç göndermese de eskisi gibi çalışmalı. Ve var olan input’ta validation’ı asla sıkılaştırmayın: kuralı gevşetmek güvenlidir, sıkmak sahadaki eski istemcileri kırar.

3. Enum ve status semantiğine dikkat. Bir enum’a yeni değer eklemek masum görünür ama eski istemci onu tanımayıp hata verebilir; yeni değerleri gate’leyin ya da uyumlu bir fallback bırakın. Aynı şekilde HTTP status kodlarının ve hata kodlarının anlamını değiştirmeyin — istemciler bunlara göre dallanıyordur.

4. Gerçekten kırıcı değişiklik için URL sürümü yerine header ile pin. Stripe’ın yaptığı gibi bir tarih/versiyon header’ı (Stripe-Version: 2026-09-30.endive) kullanın; her istemci kendi kaydolduğu sürüme sabitlenir, siz sunucu tarafında eski ve yeni şekli aynı anda servis edersiniz. Bu, sahadaki eski build’i kırmadan ilerlemenizi sağlar.

   GET /orders/42
   API-Version: 2026-10-01
   
   # Sunucu bu header'a göre yanıtı eski ya da yeni şekilde döner;
   # başlık yoksa istemcinin ilk gördüğü sürüme sabitlenir.

5. Telemetri olmadan hiçbir şeyi kaldırmayın. Sahadaki istemci sürümlerini ölçün (User-Agent, versiyon header’ı, API key başına kullanım). Bir alanı ya da eski şekli ancak hiçbir aktif build’in onu kullanmadığını gördüğünüzde emekliye ayırın. Ölçüm yoksa “kaldırmak güvenli mi” sorusunun cevabı da yoktur.

Sonuç: Ben olsam günlük değişikliklerin %90’ını additive-only + tolerant reader disipliniyle hiç sürüm açmadan yapardım: yalnızca ekle, mevcut alanlara dokunma, yeni input’ları optional tut. Kaçınılmaz bir kırıcı değişiklik geldiğinde /v2 yerine bir versiyon header’ı devreye alır, iki şekli geçiş penceresinde birlikte servis eder ve eskisini ancak telemetri sıfıra yaklaştığında kaldırırdım. Mobilde eski build’ler yıllarca yaşar; bu yüzden pin mekanizmasını gerçekten ihtiyaç duymadan, bugünden kurardım.