REST API tasarımı 101: Kaynaklar, durum kodları ve sürümleme

REST felsefesi: isimler fiil değil, HTTP fiildir

RESTful tasarımda URL’ler genelde kaynak koleksiyonlarını ve tekil kaynakları temsil eder (`/invoices`, `/invoices/{id}`). İşlemler fiil ile değil HTTP metodu (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) ve gerektiğinde alt kaynak veya eylem özel uçları ile ifade edilir. Pratikte saf REST her zaman mümkün olmaz; ancak “her şeyi POST /doSomething”e çevirmek gözlemlenebilirliği ve önbellek davranışını zayıflatır. İyi bir denge: okunabilir kaynak modeli + sınırlı sayıda kontrollü eylem uç noktası.

Durum kodları ve tutarlı hata gövdesi

200 üzerinde her şeyi döndürmek geçici olarak kolaydır fakat istemci tarafı retry ve hata sınıflandırmasını imkansızlaştırır. 4xx kullanıcı/hatalı istem girdisi, 5xx sunucu tarafı, 401/403 ayrımı authz ayrımı için kritik. Hata gövdesinde makine tarafından okunabilir bir kod (`error_code`), insan mesajı ve isteğe bağlı alan listesi standartlaştırılmalı. Loglama tarafında correlation id üst bilgisi (header) üretimde hata ayıklamayı dramatik hızlandırır.

Pagination, sıralama ve filtreleme

Offset tabanlı sayfalama basit fakat büyük tablolarda tutarsız “atlama” üretir; cursor tabanlı (keyset) pagination daha kararlıdır fakat istemci sözleşmesi daha titiz ister. Sıralama alanını beyaz listeye alın; serbest metin order parametreleri SQL enjeksiyon sınıfı risk taşır. Filtreler için açık şema (OpenAPI) paylaşın — “gizli query param” kültürü entegrasyonu yavaşlatır.

Idempotentlik ve teslim garantisi

Ödeme, stok rezervasyonu veya bildirim gönderimi gibi yan etkileri olan POST çağrıları için idempotency key desenini desteklemeniz sık gereklidir. İstemci aynı anahtarı tekrar gönderdiğinde sunucunun aynı sonucu dönmesi beklenir. Bu anahtarı veritabanında veya güvenilir cache’de saklamak TTL ve temizlik stratejisi ile birlikte tasarlanmalıdır.

Sürümleme ve geriye dönük uyumluluk

Kırıcı alan çıkarmanın yolu çoğu zaman `/v2` veya başlıkta sürüm + additive change önceliği kombinasyonudur.
Alan eklemede geriye uyum: eski istemciler bilinmeyen alanları görmezden gelmeli.
Deprecation: güneş doğma tarihi + log uyarısı + dokümantasyon üçlüsü olmadan alan düşürmeyin.
OpenAPI/JSON Schema yayınlamak onboarding maliyetini düşürür.