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

> Değişikliklerin çoğunu alan ekleyerek yapın ve hiçbir alanı silmeyin; kaçınılmaz kırıcı değişikliği /v2 yerine bir versiyon header'ıyla pin'leyin.

- Soruldu: 2026-10-04
- Yanıtlandı: 2026-10-09
- Soran: Sinan
- Etiketler: api, api-design
- Kaynak: https://muhammetsafak.com/tr/sor-bakalim/yeni-surum-acmadan-apimi-geriye-donuk-uyumlu-gelistirmek/
- Dil: tr-TR
- Yazar: Muhammet Şafak

---
**Soru:** Bir REST API'miz var ve onu mobil uygulamalar tüketiyor. Sürekli yeni alan ekleme ve bazı yanıtları değiştirme ihtiyacı doğuyor ama sahadaki eski mobil build'leri güncellemeye zorlayamıyorum — insanlar aylarca hatta yıllarca eski sürümde kalıyor.

Her seferinde `/v2`, `/v3` gibi yeni bir sürüm açmadan API'mi geriye dönük uyumlu biçimde nasıl geliştirebilirim? Hangi değişiklikler güvenli, hangileri değil ve gerçekten kırıcı bir şey yapmam gerektiğinde ne yapmalıyım?


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'ı](/tr/blog/api-tasariminda-surumleme-versioning-kararlari/) (`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.

   ```http
   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.

## İlgili Yazılar

- [API tasarımında sürümleme (versioning) kararları](/tr/blog/api-tasariminda-surumleme-versioning-kararlari/) — Blog
- [API hata gövdelerimi RFC 7807 problem+json biçimine mi taşımalıyım?](https://muhammetsafak.com/tr/sor-bakalim/api-hata-govdelerimi-rfc-7807-problem-json-tasimaliyim/) — Sor Bakalım
- [OpenAPI şemasını önce mi yazmalıyım yoksa koddan mı üretmeliyim?](https://muhammetsafak.com/tr/sor-bakalim/openapi-semasini-once-mi-yazmaliyim-yoksa-koddan-mi-uretmeliyim/) — Sor Bakalım
- [Public API'mde bir endpoint'i kullanımdan kaldırırken sunset sürecini nasıl yönetmeliyim?](https://muhammetsafak.com/tr/sor-bakalim/public-apimde-bir-endpointi-kullanimdan-kaldirirken-sunset-surecini-nasil-yonetmeliyim/) — Sor Bakalım