API Tasarımında Sık Yapılan Yedi Hata

Entegrasyon projelerinde onlarca kurumsal API gördük; hatalar şaşırtıcı biçimde aynı. İlk başarılı çağrıya giden süreyi uzatan yedi klasik:

1. Sürümsüz sözleşme. Alan silmek, tip değiştirmek, adı “düzeltmek” — hepsi birilerinin gece yarısı alarmı. /v1 ilk günden; kırıcı değişiklik yalnız yeni sürümde.

2. Anlamsız hata gövdesi. 500 {"error": "error"} bir hata mesajı değildir. İyi hata: makine-okur kod, insan-okur açıklama, izleme kimliği ve mümkünse çözüm ipucu.

3. Sayfalamasız liste. “Şimdilik az kayıt var” — iki yıl sonra 400 bin kayıtlı uç, tek istekte tabloyu döküyor. İmleç (cursor) tabanlı sayfalama baştan; offset büyük veride yalan söyler.

4. Idempotency yok. Ağ koptu, istemci tekrar denedi, ödeme iki kez geçti. Yazma uçları idempotency anahtarı kabul etmeli; aynı anahtar aynı sonucu döndürmeli.

5. Filtre diye SQL sızıntısı. ?filter=name eq 'x' derken sorgu dilini dışarı açmak. Filtre kelime dağarcığı sınırlı ve doğrulanmış olmalı; esneklik isteyen uca ayrı arama tasarlanır.

6. Saat dilimi kaosu. Tarihler ISO 8601 + UTC; yereli gösterim istemcinin işi. “Bizde tarihler İstanbul saatiyle string” cümlesi bir dahaki entegrasyonda gözyaşı demektir.

7. Dokümantasyonun kodu yalanlaması. El yazısı doküman ilk haftada bayatlıyor. Şema (OpenAPI) koddan üretilmeli, örnekler CI’da gerçek uca karşı test edilmeli.

Aslında hepsinin tek kökü var: API’yi kendi ekibiniz için değil, hiç tanımadığınız yorgun bir geliştirici için tasarlamak. O geliştirici bazen iki yıl sonraki siz oluyorsunuz.

Kurumsal API ve entegrasyon işlerinde nasıl çalıştığımız: Entegrasyon & API.