İyi tasarlanmış bir REST API tüketen geliştiriciler dokümantasyona ihtiyaç duymaz; kötü tasarlanmış biri sürekli yardım ister. Birden fazla SaaS projesinde API tasarlayıp entegre ederken öğrendiğim 12 pratiği paylaşıyorum.

1. Tutarlı Kaynak Adlandırması

# YANLIŞ
GET /getUsers
POST /createOrder
DELETE /deleteCustomer/123

# DOĞRU — kaynak çoğul, fiil yok
GET    /users
POST   /orders
DELETE /customers/123
GET    /customers/123/orders   # iç içe kaynak

2. HTTP Status Code'larını Doğru Kullanın

200 OK          → Başarılı GET, PUT
201 Created     → Başarılı POST
204 No Content  → Başarılı DELETE
400 Bad Request → Validation hatası
401 Unauthorized → Auth gerekli
403 Forbidden   → Yetkisiz
404 Not Found   → Kaynak yok
422 Unprocessable → Semantic validation hatası
429 Too Many Requests → Rate limit
500 Internal Server Error → Sunucu hatası

3. Standart Hata Yanıt Formatı

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation başarısız",
    "details": {
      "email": ["Geçersiz e-posta formatı"],
      "name": ["Ad alanı zorunludur"]
    }
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-04-08T10:30:00Z"
  }
}

4. Versioning Stratejisi

URL versioning en yaygın ve en temiz yaklaşımdır: /api/v1/users. Header versioning da kullanılabilir ama client tarafında daha fazla iş gerektirir. Sürüm değişikliklerini ne zaman yapacaksınız?

  • Mevcut field'ı kaldırıyorsanız → major version (v1 → v2)
  • Yeni zorunlu field ekliyorsanız → major version
  • Yeni opsiyonel field ekliyorsanız → minor, v1 bozulmaz

5. Cursor-based Pagination

Büyük veri setlerinde ?page=50 yerine cursor pagination kullanın — performanslıdır ve gerçek zamanlı verinin ortasında kayıt kaçırmazsınız:

{
  "data": [...],
  "pagination": {
    "next_cursor": "eyJpZCI6MTAwfQ==",
    "has_more": true,
    "per_page": 20
  }
}

6. Rate Limiting

Her API endpoint'ine rate limiting ekleyin ve client'a bilgi verin:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1712570400

7-12. Diğer Kritik Pratikler

  • 7. İdempotency: POST isteklerine idempotency key desteği ekleyin — double submit'leri önler
  • 8. Field filtering: ?fields=id,name,email ile client istediği alanları seçebilsin (over-fetching önlenir)
  • 9. OpenAPI/Swagger: Kodu yazarken değil, API kontrağı önce belirlenip dokümante edilmeli
  • 10. Request ID: Her isteğe UUID bazlı request_id ekleyin — log debugging için kritik
  • 11. CORS: Yalnızca izin verilen originlere izin verin; * kullanmayın
  • 12. Deprecation notice: Eski endpoint'leri kapatmadan önce Sunset header ile 90+ gün önceden bildirin