REST API Versiyonlama: URL vs Header, Hangisi Ölçeklenebilir?

# REST API Versiyonlama: URL vs Header, Hangisi Ölçeklenebilir?

Bir API'nı canlıya aldığında, kullanıcılar ona bağımlı hale geliyor. Sonra yeni bir özellik eklemen gerekiyor ama eski yanıtı bozacak. versiyonlama burada devreye giriyor. Peki hangi yöntem gerçekten ölçeklenebilir?

1. URL Versiyonlama (`/v1/`, `/v2/`)
En yaygın ve anlaşılır yöntem. Tarayıcıdan test etmesi kolay, cache mekanizmaları (CDN, proxy) iyi çalışır.

2. Header Versiyonlama (`Accept`, `X-API-Version`)
URL'i temiz tutar ama istemci tarafında her isteğe header eklenmesi gerekir.

3. Content Negotiation (`Accept: application/vnd.api+json;version=1`)
RESTful ilkelerine daha sadık ama karmaşık ve yaygın değil.

Basit bir Node.js + Express uygulaması kuralım:

1const express = require('express');
2const app = express();
3
4// V1 Endpoint
5app.get('/api/v1/users/:id', (req, res) => {
6res.json({
7id: req.params.id,
8name: 'John Doe',
9email: 'john@example.com'
10});
11});
12
13// V2 Endpoint - Daha fazla veri, farklı yapı
14app.get('/api/v2/users/:id', (req, res) => {
15res.json({
16id: req.params.id,
17profile: {
18firstName: 'John',
19lastName: 'Doe',
20email: 'john@example.com',
21createdAt: '2024-01-15'
22}
23});
24});
25
26app.listen(3000, () => console.log('Server running on port 3000'));

Test etmek için:

1curl http://localhost:3000/api/v1/users/1
2// Çıktı: {"id":"1","name":"John Doe","email":"john@example.com"}
3
4curl http://localhost:3000/api/v2/users/1
5// Çıktı: {"id":"1","profile":{"firstName":"John","lastName":"Doe","email":"john@example.com","createdAt":"2024-01-15"}}

URL versiyonlama kazanır çünkü:
- Routing açık ve basit
- Cache ve proxy'ler sorunsuz çalışır
- Yeni versiyon eklemek kolay
- Eski sürüm desteğini sonlandırmak net

Header yöntemi, istemci kütüphaneleri (SDK) için iyidir ama browser-based uygulamalar için URL daha pratiktir. İlk başta URL versiyonlama seç; ihtiyaç duyarsan hybrid (v1 URL + deprecation header) kullan.