REST API tasarımında en sık yapılan 9 hata ve daha iyi alternatifleri

Bir API, bir kez yayınlandıktan sonra değiştirilmesi en zor koddur. Çünkü artık sizin kontrolünüzde olmayan istemciler ona bağlıdır. Bu yüzden ilk tasarımda yapılan küçük hatalar yıllarca taşınır. Aşağıda en sık karşılaştıklarımı ve nasıl daha iyi yapılabileceklerini topladım.

1. Her şeye 200 dönmek

HTTP/1.1 200 OK
{ "success": false, "error": "Kullanıcı bulunamadı" }

İstemci önce HTTP koduna bakar. Hata durumunda 200 dönmek; önbellekleri, izleme araçlarını ve hata yakalama kodunu yanıltır. Doğru kodları kullanın:

• 400 geçersiz istek, 401 kimlik doğrulama yok, 403 yetki yok
• 404 kaynak yok, 409 çakışma (örneğin aynı e-posta zaten kayıtlı), 422 doğrulama hatası
• 429 istek sınırı aşıldı
• 500 sunucu tarafında beklenmeyen hata

2. Tutarsız hata gövdesi

Bir uç nokta {"error": "..."}, bir başkası {"message": "..."}, üçüncüsü düz metin döndürüyorsa istemci her biri için ayrı kod yazmak zorunda kalır. Tek bir biçim seçin. RFC 9457 (Problem Details) bunun için iyi bir standarttır:

{
  "type": "https://api.ornek.com/hatalar/dogrulama",
  "title": "Doğrulama hatası",
  "status": 422,
  "errors": { "email": ["Geçerli bir e-posta adresi girin."] }
}

3. Adreste fiil kullanmak

POST /getUsers
POST /createOrder
POST /deleteProduct?id=5

REST'te adres kaynağı, HTTP yöntemi ise eylemi anlatır:

GET    /users
POST   /orders
DELETE /products/5

Kaynağa tam oturmayan işlemler için alt kaynak kullanmak çoğu zaman daha okunaklıdır: POST /orders/42/cancel.

4. Sayfalama olmadan liste döndürmek

GET /orders bugün 50 kayıt döner. İki yıl sonra 400.000 kayıt döner ve sunucunuzu kilitler. İlk günden sayfalama ekleyin. Büyük ve sürekli değişen veride imleç (cursor) tabanlı sayfalama, ?page= yönteminden daha tutarlı sonuç verir:

{ "data": [ ... ], "next_cursor": "eyJpZCI6MTAyNH0" }

5. Sürümleme planı olmamak

Bir alanın adını değiştirmeniz ya da bir alanı kaldırmanız gerektiğinde ne olacak? En basit ve en yaygın yöntem adreste sürüm taşımaktır: /v1/orders. Hangi yöntemi seçerseniz seçin, kuralı baştan koyun. Alan eklemek genellikle geriye dönük uyumludur; alan silmek ya da anlamını değiştirmek değildir.

6. Veritabanını olduğu gibi dışarı açmak

Tablo satırını doğrudan JSON'a çevirip döndürmek kolaydır. Ama bu, iç yapınızı (sütun adları, password_hash, is_deleted) dışarı sızdırır ve veritabanını değiştirmenizi imkânsız hâle getirir. Ayrı bir yanıt modeli tanımlayın ve yalnızca istemcinin ihtiyacı olan alanları açık edin.

7. Tekrar denenebilir istekleri düşünmemek

Mobil bir istemci ödeme isteği gönderir, bağlantı kopar ve istek yeniden gönderilir. Sonuç: iki kez çekilen para. Para ya da sipariş oluşturan POST isteklerinde bir idempotency anahtarı kabul edin:

POST /payments
Idempotency-Key: 6f1c2a9e-…

Aynı anahtarla gelen ikinci istek, yeni bir işlem başlatmak yerine ilk isteğin sonucunu döndürür.

8. Tarihleri ve parayı belirsiz bırakmak

• Tarihleri her zaman ISO 8601 biçiminde ve saat dilimiyle verin: 2026-10-26T17:00:00Z. 26/10/2026 gibi bir biçim, ülkeye göre farklı okunur.
• Parayı ondalık sayı (19.99) olarak değil, en küçük birimde tam sayı (1999) ve para birimiyle birlikte verin. Kayan noktalı sayılar kuruşları kaybettirir.

9. İstek sınırı ve zaman aşımı yok

Kötü niyetli olması gerekmez; hatalı bir döngüye giren tek bir istemci bile API'nizi çökertebilir. İstek sınırı uygulayın ve sınır aşıldığında 429 ile birlikte Retry-After başlığı dönün. Kendi tarafınızda da dış servislere yaptığınız her çağrıya bir zaman aşımı koyun.

Son bir öneri: Önce belgeyi yazın

Uç noktaları kodlamadan önce bir OpenAPI belgesi yazmak, yukarıdaki hataların çoğunu daha tasarım aşamasında görünür kılar. Ayrıca istemci ekibi siz kod yazarken belgeye göre çalışmaya başlayabilir. Belge, API'nin sözleşmesidir; kod ise o sözleşmenin uygulaması.