REST API Tasarımında İyi Uygulamalar

Bir API tasarlamak, sadece endpoint yazmaktan çok daha fazlasıdır. İyi tasarlanmış bir REST API; geliştirici deneyimini iyileştirir, bakım maliyetini düşürür ve sistemler arasındaki entegrasyonu kolaylaştırır. Yıllar içinde edindiğim deneyimlere dayanarak, REST API tasarımında dikkat edilmesi gereken en kritik noktaları bu yazıda derledim.

1. Kaynak Adlandırmasında Tutarlılık

REST'in temelinde kaynaklar yatar. Endpoint isimlerini fiil değil, isim olarak tanımlamak gerekir.

• ❌ /getUsers, /createOrder, /deleteProduct
• ✅ /users, /orders, /products

Kaynaklar çoğul yazılmalı ve hiyerarşi mantıklı kurulmalıdır: /users/{id}/orders/{orderId} gibi. Büyük-küçük harf tutarsızlıklarından kaçının; kebab-case URL'lerde en yaygın ve okunabilir tercih olarak öne çıkar.

2. HTTP Metodlarını Doğru Kullanın

Her metodun anlamı vardır ve bu anlama sadık kalmak, API'nizi kullanan geliştiricilerin zihninde doğal bir model oluşturur:

| Metod | Kullanım | |-------|----------| | GET | Veri okuma | | POST | Yeni kaynak oluşturma | | PUT | Kaynağı tamamen güncelleme | | PATCH | Kaynağı kısmen güncelleme | | DELETE | Kaynağı silme |

POST ile her şeyi yapmak kısa vadede kolay görünür; ama uzun vadede bakımı zorlaşan, belgelenmesi güç bir API ortaya çıkar.

3. Anlamlı HTTP Durum Kodları Döndürün

200 OK her şeye cevap değildir. Durum kodlarını doğru kullanmak, istemcilerin hataları programatik olarak yönetmesini sağlar:

• 201 Created → Yeni kaynak başarıyla oluşturuldu
• 400 Bad Request → İstemci hatası, eksik veya geçersiz veri
• 401 Unauthorized → Kimlik doğrulama gerekli
• 403 Forbidden → Yetki yok
• 404 Not Found → Kaynak bulunamadı
• 422 Unprocessable Entity → Validasyon hatası
• 500 Internal Server Error → Sunucu taraflı hata

4. Sürümleme (Versioning) Stratejisi Belirleyin

API'ler zamanla evrilir. Geriye dönük uyumluluğu korumak için baştan bir sürümleme stratejisi benimsemek şarttır. En yaygın yöntem URL tabanlı sürümlemedir:

/api/v1/users
/api/v2/users

Alternatif olarak HTTP header'ları (Accept: application/vnd.myapi.v2+json) kullanılabilir; ancak URL tabanlı yöntem daha kolay test edilir ve belgelenir.

5. Sayfalama, Filtreleme ve Sıralama

Büyük veri setlerini tek seferde döndürmek hem performansı hem de kullanıcı deneyimini olumsuz etkiler. Şu parametreleri standart hale getirmenizi öneririm:

• Sayfalama: ?page=2&limit=20 veya cursor tabanlı (?cursor=abc123)
• Filtreleme: ?status=active&role=admin
• Sıralama: ?sort=createdAt&order=desc

Bu parametreleri tutarlı biçimde tüm collection endpoint'lerinde sunmak, API'nizin tahmin edilebilirliğini artırır.

6. Hata Yanıtlarını Standartlaştırın

Hata mesajları ne kadar bilgilendirici olursa, entegrasyon süreci o kadar hızlanır. Her hata yanıtı en azından şunları içermeli:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "E-posta adresi geçersiz.",
    "field": "email"
  }
}

Güvenlik açısından hassas bilgileri (stack trace, veritabanı hataları) asla istemciye yansıtmayın.

7. Belgeleme ve Sözleşme

Yazdığınız API'nin değeri, belgesiyle doğru orantılıdır. OpenAPI (Swagger) standartı ile hem insan okunabilir hem de makine işlenebilir bir belge üretebilirsiniz. swagger-ui gibi araçlarla bu belgeyi interaktif hale getirmek, geliştirici onboardingini ciddi ölçüde hızlandırır.

---

Sonuç olarak, iyi bir REST API tasarımı disiplin ve tutarlılık gerektirir. Yukarıdaki pratiklerin hepsini bir anda uygulamak zorunda değilsiniz; ancak her yeni projede bir öncekinden daha bilinçli kararlar almak, zamanla sizi gerçekten sürdürülebilir sistemler inşa eden bir geliştirici yapar.