Yıllar içinde farklı ekiplerin API'lerini incelerken (ve kendi ilk API'lerimde) sürekli tekrar eden bir dizi hata fark ettim. Bu yazıda, en sık gördüğüm 7 hatayı ve bunları ASP.NET Core projelerinde nasıl önlediğimi paylaşıyorum.

1. Fiilleri URL'ye Koymak

/getUserOrders yerine GET /users/{id}/orders kullanmak, REST'in kaynak (resource) odaklı felsefesine uyar. HTTP metodu zaten fiili taşıyor; URL sadece kaynağı tanımlamalı.

2. Her Şeye 200 Dönmek

Bir kaynak bulunamadığında 200 dönüp gövdede {"error": "not found"} yazmak, istemci tarafında hata yönetimini zorlaştırıyor. 404, 400, 409, 422 gibi anlamlı HTTP durum kodlarını kullanmak, istemcinin tek bir yerde (status code) hata olup olmadığını anlamasını sağlıyor.

3. Versiyonlamayı Hiç Düşünmemek

API'nin ilk versiyonunu yayınladıktan sonra, geriye dönük uyumluluğu bozmadan değişiklik yapmak zorlaşıyor. Baştan /api/v1/... gibi bir versiyon segmenti eklemek, ileride kırıcı değişiklik yapmam gerektiğinde eski istemcileri kırmadan yeni bir versiyon sunmamı sağlıyor.

4. Tutarsız İsimlendirme

Bir endpoint'te camelCase, başka birinde snake_case kullanmak küçük bir detay gibi görünse de, entegrasyon yapan ekipler için sürekli sürpriz kaynağı oluyor. Tüm API yüzeyinde tek bir isimlendirme standardı (genelde camelCase) belirleyip, bunu System.Text.Json ayarlarında merkezi olarak zorunlu kılıyorum.

5. Sayfalama (Pagination) Olmadan Liste Dönmek

"Şimdilik az veri var" diyerek sayfalamasız bir liste endpoint'i yazmak, veri büyüdükçe performans sorununa dönüşüyor. Baştan ?page=1&pageSize=20 gibi bir sözleşme kurmak, ileride veri arttığında API sözleşmesini değiştirmek zorunda kalmamı engelliyor.

public record PagedResult<T>(
    IReadOnlyList<T> Items,
    int Page,
    int PageSize,
    int TotalCount
);

6. Hata Mesajlarını İstemciye Göre Değil, Kendine Göre Yazmak

"NullReferenceException at line 42" gibi ham hata mesajlarını doğrudan istemciye döndürmek hem güvenlik açısından riskli hem de kullanışsız. RFC 7807 (Problem Details) formatını kullanarak, hem insan hem makine tarafından okunabilir, standart bir hata gövdesi döndürüyorum.

7. Kimlik Doğrulama ve Yetkilendirmeyi Sonradan Eklemek

Güvenliği "işler çalışsın da sonra ekleriz" diyerek ertelemek, projede en çok pişman olduğum kararlardan biriydi. JWT tabanlı kimlik doğrulama ve endpoint bazlı yetkilendirme (policy/role based) kurallarını, ilk endpoint'i yazdığım günden itibaren projeye dahil ediyorum artık.

Sonuç

Bu hataların ortak noktası, çoğunun "şimdilik" mantığıyla ertelenmesi. Küçük bir projede fark etmeyebilir, ama API başka sistemlerle entegre olmaya başladığında bu kısayolların bedeli katlanarak artıyor. Baştan doğru sözleşmeyi kurmak, sonradan düzeltmekten her zaman daha ucuza geliyor.