REST API Tasarımı: En İyi Uygulamalar ve Sık Yapılan Hatalar

İyi tasarlanmış bir API kullanması keyif verir. Kötü tasarlanmış bir API ise hayal kırıklığına ve hatalara yol açar. İşte geliştiricilerin severek kullanacağı API'ları nasıl tasarlayacağınız.

Temel İlkeler

1. Fiiller Yerine İsimler Kullanın

✅ GET /users
❌ GET /getUsers

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

• GET: Veri Oku
• POST: Veri Oluştur
• PUT: Veri Güncelle (değiştir)
• PATCH: Kısmi güncelleme
• DELETE: Veri Sil

3. Uygun Durum Kodlarını Kullanın

• 200: Başarılı
• 201: Oluşturuldu
• 400: Hatalı İstek
• 401: Yetkisiz
• 404: Bulunamadı
• 500: Sunucu Hatası

Yanıt Formatı

Tutarlı Yapı

Verileri her zaman tutarlı bir formatta, kod, mesaj ve detayları içeren uygun hata nesneleriyle döndürün.

Sayfalama

Liste uç noktaları için, toplam öğe sayısı, sayfa numarası, sayfa başına öğe ve toplam sayfa sayısı ile sayfalama meta verilerini ekleyin.

Versiyonlama

URL Versiyonlama

En yaygın ve açık: /api/v1/users

Başlık Versiyonlama

Daha temiz URL'ler ama daha az görünür: Accept: application/vnd.api+json;version=1

Kimlik Doğrulama

JWT (JSON Web Tokens)

Durumsuz, ölçeklenebilir, SPA'lar ve mobil uygulamalar için iyi.

API Anahtarları

Basit, sunucudan sunucuya iletişim için iyi.

OAuth 2.0

Üçüncü taraf erişimi ve karmaşık yetkilendirme için.

Dokümantasyon

OpenAPI/Swagger

Etkileşimli test ile API dokümantasyonu için standart.

Örnekler

Her zaman istek/yanıt örnekleri ekleyin.

Sık Yapılan Hatalar

1. HTTPS kullanmamak: Üretimde her zaman şifreleyin
2. Hassas verileri ifşa etmek: Ne döndürdüğünüze dikkat edin
3. Oran sınırlaması olmaması: Kötüye kullanıma karşı koruyun
4. Kötü hata mesajları: Geliştiricilerin hata ayıklamasına yardımcı olun

Sonuç

İyi API tasarımı zaman alır ancak geliştirici deneyimi ve azalan destek yükü açısından karşılığını verir.