REST API Tasarımında İyi Uygulamalar

Bir API tasarlarken verdiğiniz kararlar, yalnızca bugünkü geliştirici deneyimini değil; aylarca, hatta yıllarca sürecek entegrasyonları, bakım maliyetlerini ve sistemin büyüme kapasitesini doğrudan etkiler. REST API'ler artık neredeyse her modern uygulamanın omurgası hâline geldi. Peki bu omurgayı sağlam inşa etmek için nelere dikkat etmeliyiz?

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

REST'in temel felsefesi "her şey bir kaynaktır" ilkesine dayanır. Bu yüzden endpoint adlarını isimlerle tanımlayın, fiillerden kaçının.

• ✅ GET /users → Kullanıcıları listele
• ✅ POST /orders → Yeni sipariş oluştur
• ❌ GET /getUsers → Yanlış, fiil kullanılmış
• ❌ POST /createOrder → Yanlış, HTTP metodu zaten eylemi belirtir

Çoğul isimleri tercih edin (/user yerine /users) ve tutarlı bir kebab-case veya snake_case politikası belirleyip ona sadık kalın.

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

Her HTTP metodunun semantik bir anlamı vardır; bu anlamları çiğnemek API'nizi kara kutuya dönüştürür.

| Metot | Kullanım Amacı | |-------|----------------| | GET | Veri okuma (yan etki yok) | | POST | Yeni kaynak oluşturma | | PUT | Kaynağı tamamen güncelleme | | PATCH | Kaynağı kısmen güncelleme | | DELETE | Kaynağı silme |

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

200 OK her şey için yetmez. Hata yönetimini de standartlaştırın:

• 201 Created → Kayıt başarıyla oluşturuldu
• 400 Bad Request → İstemci tarafı hata (validasyon, eksik alan)
• 401 Unauthorized → Kimlik doğrulama gerekli
• 403 Forbidden → Yetkisiz erişim
• 404 Not Found → Kaynak bulunamadı
• 422 Unprocessable Entity → İş kuralı ihlali
• 500 Internal Server Error → Sunucu tarafı hata

Hata yanıtlarınızı da standart bir formatta yapılandırın; code, message ve varsa details alanlarını ekleyin.

4. Versiyonlama Stratejisi Belirleyin

API'niz bir gün değişecek. Bu kaçınılmaz. Geriye dönük uyumluluğu korumak için en başından bir versiyonlama stratejisi benimseyin:

• URI versiyonlama: /api/v1/users → En yaygın ve anlaşılır yöntem
• Header versiyonlama: Accept: application/vnd.myapi.v1+json → Daha temiz URI'ler ama daha az görünür

5. Filtreleme, Sıralama ve Sayfalama

Büyük veri setlerini döndürmek hem istemciyi hem de sunucuyu yorar. Şu parametreleri standart hâle getirin:

• GET /products?category=elektronik&sort=price&order=asc
• GET /products?page=2&limit=20

Sayfalama yanıtlarında toplam kayıt sayısını (total) ve sonraki/önceki sayfa bilgilerini de döndürün. Bu, istemci tarafında çok daha iyi bir deneyim sağlar.

6. Güvenliği İhmal Etmeyin

• Her endpoint için kimlik doğrulama (JWT, OAuth 2.0) zorunlu tutun.
• Gereksiz alanları response body'den çıkarın; hassas veriyi asla sızdırmayın.
• Rate limiting uygulayın; kötü niyetli ya da hatalı istemcilerin sistemi yormasını önleyin.
• HTTPS kullanımını zorunlu hâle getirin, HTTP'ye izin vermeyin.

7. Dokümantasyonu Kodla Birlikte Yaşatın

Kodu yazan kişiyle API'yi kullanan kişi çoğu zaman farklı insanlardır. Swagger/OpenAPI gibi araçlarla dokümantasyonunuzu otomatik oluşturun ve güncel tutun. İyi bir dokümantasyon, support yükünüzü ciddi ölçüde azaltır.

---

REST API tasarımı bir kez yapılıp unutulan bir şey değil; zamanla evrilen, büyüyen ve bakım gerektiren canlı bir yapıdır. Yukarıdaki pratikleri erkenden benimsemek, ilerleyen süreçte "keşke baştan yapsaydım" pişmanlığının önüne geçer. Siz de kendi projelerinizde hangi noktaları en zorlu buluyorsunuz? Yorumlarda buluşalım.