REST API tasarımı: adresler, yanıtlar ve sayfalama
Bir API'yi kullanmak, adresler ve yanıtlar tutarlı olduğunda kolaylaşır. Kaynak adları, HTTP metotları, hata biçimi ve sayfalama kararlarını aynı sözleşmenin parçaları olarak ele alın.
URL Yapısı
Kaynak odaklı URL'ler kullanın:
- Çoğul isimler tercih edin (/users, /products)
- Fiillerden kaçının (/getUser yerine GET /users/:id)
- İç içe kaynakları mantıklı kullanın (/users/:id/orders)
HTTP Metodları
Her metodu amacına uygun kullanın:
- GET: Veri okuma (idempotent)
- POST: Yeni kaynak oluşturma
- PUT: Kaynağı tamamen güncelleme
- PATCH: Kaynağı kısmen güncelleme
- DELETE: Kaynak silme
Hata Yönetimi
HTTP durum kodunu yanıtın durumuyla tutarlı seçin. Yanıt gövdesinde uygulama hata kodu ve anlaşılır bir mesaj sunabilirsiniz. Ayrıntılara günlük kayıtlarını, gizli bilgileri veya sunucu iç yapısını eklemeyin.
Sayfalama ve Filtreleme
Sık değişen veya büyük listelerde imleç tabanlı sayfalama uygun olabilir. Sıralamanın kararlı olmasını ve aynı kaydın iki sayfada tekrarlanmamasını sağlayın. Sayfa numarasına doğrudan geçiş gerekiyorsa offset tabanlı yaklaşımın maliyetini ölçün.
Versiyon Yönetimi
Uyumsuz değişikliklerin nasıl yayınlanacağını baştan belirleyin. URL içinde v1 veya v2 gibi bir sürüm belirtmek seçeneklerden biridir; eski istemciler için geçiş ve kaldırma tarihlerini açıklayın.
Rate Limiting
Kullanım sınırlarını ve sınır aşıldığında beklenen yanıtı açıklayın. İstemcinin ne zaman yeniden deneyebileceğini yanıt başlıklarında belirtin.
Sonuç
Sözleşmeyi örnek istekler, hata yanıtları ve sayfalama senaryolarıyla belgeleyin. Örneklerin uygulamanın gerçek davranışıyla eşleştiğini test edin.
