Yıllar içinde yüzlerce REST API inceledim — bir geliştirici olarak, kod inceleyici olarak ve laptopumu pencereden atmak istemememe neden olan üçüncü parti API'lerle entegre olması gereken biri olarak. Aynı hatalar sürekli karşıma çıkıyor ve sinir bozucu olan şey, bunların çoğunu bildiğinizde düzeltmenin kolay olması.
İşte en sık gördüklerim ve bunun yerine ne yapılması gerektiğine dair net örnekler.
Hata 1: URL'lerde Fiiller
Özellikle ilk API'sini oluşturan geliştiricilerden en yaygın hata budur.
Yanlış: POST /api/createUser GET /api/getUsers
Doğru: POST /api/users (oluştur) GET /api/users (listele) GET /api/users/5 (bir tane al) PUT /api/users/5 (güncelle) DELETE /api/users/5 (sil)
HTTP metodu zaten eylemi söylüyor. URL kaynağı (ne) tanımlamalı, işlemi (nasıl) değil. URL'leri isim olarak düşünün, fiil olarak değil.
Bu sadece stil tercihi değil — REST'in temelidir. URL'ler kaynak tabanlı olduğunda istemciler API yapısını tahmin edebilir. /api/users endpoint'i olduğunu biliyorsam, /api/posts ve /api/comments in aynı şekilde çalıştığını tahmin edebilirim.
Hata 2: Tutarsız İsimlendirme
Aynı proje içinde isimlendirme kurallarını karıştıran API'ler gördüm:
Yanlış (karışık kurallar): /api/blog-posts (kebab-case) /api/user_profiles (snake_case) /api/orderItems (camelCase)
Doğru (tutarlı kebab-case): /api/blog-posts /api/user-profiles /api/order-items
Kebab-case URL'ler için en yaygın kuraldır çünkü okunabilir ve URL güvenlidir. Ama belirli kural tutarlılıktan daha az önemlidir. Birini seçin ve tüm API'nizde bağlı kalın.
Ayrıca koleksiyon endpoint'leri için çoğul isimler kullanın: /api/users, /api/user değil.
Hata 3: Uygun Durum Kodları Kullanmamak
Her şey için HTTP 200 döndüren ve gerçek durumu yanıt gövdesine koyan API'ler gördüm. Bu korkunçtur çünkü HTTP istemcileri, proxy'ler ve izleme araçlarının hepsi ne olduğunu anlamak için durum kodlarına güvenir.
Yanlış: HTTP 200 { "success": false, "error": "Kullanıcı bulunamadı" }
Doğru: HTTP 404 { "message": "Kullanıcı bulunamadı" }
Bilmeniz gereken durum kodları:
- 200 Başarılı GET, PUT
- 201 Oluşturuldu (başarılı POST)
- 204 İçerik Yok (başarılı DELETE)
- 400 Geçersiz İstek (doğrulama hataları)
- 401 Yetkisiz (kimlik doğrulanmamış)
- 403 Yasaklı (doğrulanmış ama yetkili değil)
- 404 Bulunamadı
- 409 Çatışma (tekrar kaynak)
- 429 Çok Fazla İstek (hız limiti aşıldı)
- 500 Sunucu Hatası
401 ve 403 arasındaki farka özellikle dikkat edin. Bunu yanlış yapmak API'nizle entegre olan her frontend geliştiriciyi şaşırtır.
Hata 4: Aşırı İç İçe URL'ler
Yanlış: /api/companies/5/departments/3/employees/42/projects/7/tasks
Daha iyi: /api/tasks?project_id=7 /api/projects/7/tasks
İkiden fazla iç içe seviye API'nizi kullanmayı zorlaştırır. Daha derine inmeye cazip olduğunuzda kendinize sorun: bu alt kaynak doğrudan erişilebilir mi?
Hata 5: Sayfalama Yok
Tüm kayıtları döndürmek saatli bir bombadır:
{
"content": [...20 kullanıcı...],
"totalElements": 50000,
"totalPages": 2500,
"number": 0,
"size": 20
}
Liste endpoint'lerini her zaman sayfalayın. Makul bir varsayılan sayfa boyutu (20 yaygındır) ve bir maksimum (100 makuldür) belirleyin.
Yüksek performanslı API'ler için offset tabanlı yerine imleç tabanlı sayfalamayı düşünün.
Hata 6: Dahili Sıralı ID'leri Göstermek
Bu hem tasarım hem güvenlik sorunudur. Sıralı ID'ler kaç kullanıcınız olduğunu, büyüme hızını ortaya çıkarır ve tüm kaynakları numaralandırmayı önemsiz hale getirir. UUID kullanın.
Hata 7: Sürümlemeyi Çok Geç Olana Kadar Görmezden Gelmek
Bir gün API'nizde kırıcı bir değişiklik yapmanız gerekecek. Sürümleme planlamadıysanız tüm mevcut istemcileri kırmak veya çirkin geriye uyumlu hack'leri sürdürmek arasında seçim yapmak zorunda kalırsınız.
URL sürümleme (en yaygın, en kolay):
/api/v1/users
/api/v2/users
Hata 8: Tutarsız Hata Yanıtları
API'nizdeki her hata aynı yapıyı takip etmelidir:
{
"status": 400,
"message": "Doğrulama başarısız",
"errors": [
{
"field": "email",
"message": "geçerli bir e-posta adresi olmalıdır"
},
{
"field": "password",
"message": "en az 8 karakter olmalıdır"
}
]
}
Backend'inizde bir hata yanıtı sınıfı oluşturun ve global exception handler aracılığıyla tutarlı kullanın.
Hata 9: Hız Sınırlama Olmadan Genel Endpoint'ler
Hız sınırlaması olmayan herhangi bir genel API kötüye kullanıma davetiyedir. Tek bir istemci saniyede binlerce istekle sunucunuzu doldurabilir.
Hata 10: Çok Fazla veya Çok Az Veri Döndürmek
Tam olarak neyin döndürüleceğini kontrol etmek için DTO'lar kullanın. Dahili uygulama detaylarını, hassas verileri veya veritabanı entity'lerini doğrudan asla göstermeyin.
Yayın Öncesi Kontrol Listesi
Bir API göndermeden önce kontrol edin: İsim URL'ler, tutarlı isimlendirme, doğru HTTP metotları, doğru durum kodları, tüm listelerde sayfalama, girdi doğrulama, tutarlı hata formatı, kimlik doğrulama ve yetkilendirme, hız sınırlama, API belgeleri, yanıtlarda hassas veri yok, CORS doğru yapılandırılmış.
Sonuç
İyi API tasarımı kuralları körü körüne takip etmek değildir. API'nizi tahmin edilebilir yapmaktır. Geliştiriciler belgeleri okumadan bir endpoint'in nasıl çalıştığını tahmin edebildiğinde, hata mesajları tam olarak neyin yanlış gittiğini söylediğinde — bu iyi tasarlanmış bir API'dir.
API tasarımına koyduğunuz çaba her gün geri öder — daha az destek sorusu, daha hızlı entegrasyonlar ve daha az hata.
Yorumlar (