Başlıca API versiyonlama stratejileri nelerdir ve bir versiyonu nasıl deprecate edersiniz?

Question

IT Interview Practice · Accepted Answer

Versiyonlama, mevcut client'ları bozmadan bir API'yi **breaking change**'lerle geliştirmenizi sağlar. Üç ana strateji ve bir deprecation süreci vardır.

## Üç strateji

**1. URI versiyonlama** — versiyon path'tedir.
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
En basit ve en görünür olanı; route etmesi, cache'lemesi ve bir tarayıcıda test etmesi kolay. Dezavantaj: teknik olarak "URI bir resource'u tanımlar" ilkesini ihlal eder (aynı user artık iki URL'ye sahip). Bu, açık ara en yaygın tercihtir (GitHub, tarihsel olarak Stripe).

**2. Custom header versiyonlama** — versiyon bir header'da taşınır.
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
URL'leri temiz tutar ama bir tarayıcıda görünmez ve cache'lemesi daha zordur.

**3. Media-type (content negotiation) versiyonlama** — versiyon `Accept`'te.
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
En "RESTful" olanı (resource URL'si sabittir; yalnızca representation'ı versiyonlanır), ama tüketiciler için en az erişilebilir olanı.

## Neye breaking sayılır

```text
BREAKING      → remove/rename a field, change a type, change auth, tighten validation
NON-BREAKING  → add a new optional field, add a new endpoint, add an enum value*
```
Yalnızca breaking change'ler yeni bir versiyon gerektirir; non-breaking değişiklikleri mevcut olana ekleyin.

## Deprecation süreci

1. Docs ve changelog'da tarihlerle **duyurun**.
2. Client'ların programatik olarak fark etmesi için header'larla **çalışma zamanında sinyal verin**:
```http
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Jan 2026 23:59:59 GMT
Link: <https://api.example.com/v2/users/42>; rel="successor-version"
```
3. Eski versiyonun kullanımını **izleyin** ve kalan çağıranlarla iletişime geçin.
4. Yalnızca kullanım sıfıra yaklaştıktan sonra **sunset** yapın.

## Neden önemli

Mülakatçılar bunu, bir API'yi production'da ona bağımlı client'ları bozmadan büyütüp büyütemeyeceğinizi görmek için sorar — teorik değil, gerçek bir operasyonel kaygı. En güçlü cevaplar iki ayrım yapar: birincisi, **çoğu değişiklik non-breaking'tir** ve hiç versiyon artışı tetiklememelidir (ekleyici değişiklikler mevcut versiyona girer), versiyonlamayı gerçekten breaking olan değişikliklere saklar; ikincisi, *strateji*, *süreçten* daha az önemlidir — `Deprecation`/`Sunset` header'ları ve kullanım izleme ile net bir deprecation takvimi, tüketicileri asıl koruyan şeydir. URI versiyonlama pratikte görünürlüğü ve araç desteği sayesinde kazanır, ama ödünleşimleri bilmek (header ve media-type URL'leri sabit tutar ve daha RESTful'dur, keşfedilebilirlik pahasına) yalnızca `/v1/`'i taklit etmek yerine tasarım alanını anladığınızı gösterir.

Üç strateji

Neye breaking sayılır

Deprecation süreci

Neden önemli

İlgili sorular