REST API tasarımı, endpoint yazmaktan çok sözleşme tasarlamaktır. Sözleşme kötü olursa, bir süre sonra “client’lar bozulmasın diye” her şey geriye dönük hack’e dönüşür.
Bu yazıda üretimde sürdürülebilir REST API için pratik prensipleri topladım: kaynak modelleme, HTTP semantiği, idempotency, pagination, hata modeli ve versiyonlama.
1) Kaynak (resource) modeli: fiil değil isim
URI’lar “iş” değil “şey” olmalı:
- ✅
/users/{id} - ❌
/getUser
HTTP method’ları semantik taşır:
GET: okuma (idempotent)POST: oluşturma/command (idempotent olmayabilir)PUT: replace (idempotent)PATCH: partial update (genelde idempotent tasarlanır)DELETE: silme (idempotent)
2) Idempotency: retry ile hayatta kal
Üretimde retry olur. Bu yüzden özellikle POST için idempotency anahtarı ciddi fark yaratır.
3) Pagination: OFFSET yerine cursor
OFFSET büyüdükçe maliyet artar ve tutarlılık bozulur. Cursor tabanlı pagination üretimde daha sağlıklıdır.
4) Hata sözleşmesi: tek format, aksiyonlanabilir mesaj
Tek bir hata modeli kullanın:
{
"error": {
"code": "INVALID_ARGUMENT",
"message": "email is required",
"requestId": "..."
}
}5) Versiyonlama: kırmadan evrimleştir
Kural: breaking change varsa versiyon artır. Mümkünse “additive change” ile ilerle (yeni alan ekle, eskisini deprecate et).
Sonuç
REST API tasarımında hedef: client’ın doğru kullanımı kolay, yanlış kullanımı zor olsun. Idempotency, hata sözleşmesi ve pagination gibi detaylar; üretimde en çok problem çıkaran yerlerdir.