API Versioning Nedir? Geriye Uyumlu API Tasarımı

API'nize yeni alanlar eklemek mevcut kullanıcıları bozuyor mu? Eski endpoint'leri ne zaman kaldıracağınızı bilemiyor musunuz? API Versioning ile mevcut istemcileri bozmadan API'nizi geliştirin.

Neden Versioning?

API'niz yayınlandıktan sonra onu kullanan istemciler (mobil uygulama, üçüncü parti) var. Breaking change yaparsanız hepsi bozulur:

Breaking Change Örnekleri:
  ❌ Zorunlu alan ekleme
  ❌ Alan silme veya yeniden adlandırma
  ❌ Yanıt yapısını değiştirme
  ❌ Hata formatını değiştirme

Non-Breaking Change Örnekleri:
  ✅ Opsiyonel alan ekleme
  ✅ Yeni endpoint ekleme
  ✅ Yeni opsiyonel query parametresi

Versioning Stratejileri

1. URI Versioning (Önerilen)

GET /api/v1/users/42
GET /api/v2/users/42

Avantaj: Açık, anlaşılır, cache dostu Dezavantaj: URL kirliliği

2. Header Versioning

GET /api/users/42
Accept: application/vnd.myapp.v2+json

Avantaj: Temiz URL Dezavantaj: Tarayıcıda test etmek zor

3. Query Parameter

GET /api/users/42?version=2

Avantaj: Basit Dezavantaj: Cache sorunları, opsiyonel olması

4. Content Negotiation

GET /api/users/42
Accept: application/json; version=2

Semantic Versioning

v2.3.1
 │ │ └─ PATCH: Bug fix (geriye uyumlu)
 │ └── MINOR: Yeni özellik (geriye uyumlu)
 └─── MAJOR: Breaking change

API'de genellikle sadece MAJOR versiyon kullanılır: /api/v1/, /api/v2/

Versioning Implementasyonu (Express)

// Yöntem 1: Router bazında
import { Router } from 'express';

const v1Router = Router();
v1Router.get('/users/:id', (req, res) => {
  res.json({ id: req.params.id, name: 'Ali' });
});

const v2Router = Router();
v2Router.get('/users/:id', (req, res) => {
  res.json({
    id: req.params.id,
    name: 'Ali',
    profile: { avatar: 'url', bio: '...' } // v2'de eklendi
  });
});

app.use('/api/v1', v1Router);
app.use('/api/v2', v2Router);

Deprecation Stratejisi

1. Announce: v1 deprecated olduğunu duyurun
2. Header: Sunset header ekleyin
3. Timeline: 6-12 ay geçiş süresi verin
4. Monitor: v1 kullanımını izleyin
5. Remove: Kullanım sıfıra yaklaştığında kaldırın

Sunset Header

HTTP/1.1 200 OK
Sunset: Sat, 01 Jan 2027 00:00:00 GMT
Deprecation: true
Link: <https://api.example.com/v2/docs>; rel="successor-version"

Evolution Stratejisi (Versioning Olmadan)

Bazı API'ler versiyon yerine geriye uyumlu evrim tercih eder:

// v1 yanıtı
{ "name": "Ali Yılmaz" }

// Evrim: name'i koru, firstName/lastName ekle
{
  "name": "Ali Yılmaz",           // Eski istemciler için korunur
  "firstName": "Ali",              // Yeni istemciler için
  "lastName": "Yılmaz"             // Yeni istemciler için
}

Best Practices

Mümkün olduğunca versiyonlamaktan kaçının — Geriye uyumlu değişiklikler tercih edin
Breaking change yapmadan önce düşünün — Gerçekten gerekli mi?
Deprecation policy belirleyin — Minimum 6 ay geçiş süresi
Changelog tutun — Her sürümde ne değişti?
En fazla 2 aktif versiyon — Daha fazlası bakım yükü getirir
API dokümanı güncel tutun — Swagger/OpenAPI ile otomatikleştirin

Sonuç

API Versioning, istemcilerinizi bozmadan API'nizi geliştirmenin yoludur. URI versioning en yaygın ve önerilen yöntemdir. Ancak en iyi strateji, versioning ihtiyacını minimuma indirecek geriye uyumlu tasarım yaklaşımıdır.

API tasarımı ve versioning'i LabLudus platformunda öğrenin.

API Versioning Nedir?