Bir API tasarımının kalitesi, yalnızca doğru istek geldiğinde verdiği yanıtta anlaşılmaz. Yeni alan eklediğinizde kaç yeri değiştiriyorsunuz? Çağıran uygulama bir hatadan sonra ne yapacağını anlayabiliyor mu? Aynı istek ikinci kez gelirse ne oluyor? Bu soruları küçük bir projede çözmek, gerçek sistem bağlantısından sonra çözmekten daha kolaydır.
Aynı anlamı paylaşın; yalnızca aynı şekli değil
İki request bugün customerId ve quantity içeriyor diye mutlaka aynı şemayı kullanmaları gerekmez. Önizleme için müşteri kodu isteğe bağlı olabilirken siparişi kesinleştirmek için zorunlu olabilir. İkisinin değişme nedenleri farklıysa PreviewRequest ve CreateOrderRequest gibi ayrı modeller daha açık olur.
Buna karşılık bütün API’lerde aynı anlama gelen hata alanları iyi bir ortak model adayıdır. Ortak hata örneği, tek Problem tanımını üç işlemde kullanır.
| Karar | Kendinize soracağınız soru | Uygulama |
|---|---|---|
| Ortak schema | Bir kural değişince bütün kullanıcıları aynı nedenle etkilenmeli mi? | Evetse Components altında tek model ve $ref kullanın. |
| Ayrı request ve response | İstemci hangi alanları gönderir, servis hangilerini hesaplar? | Miktarı request’e, hesaplanan toplamı response’a koyun. |
| Ortak response | Açıklama, media type ve gövde modeli aynı mı? | components.responses ile bütün yanıt tanımını paylaşın. |
| Ortak route | Aynı adımlar her çağıran için aynı işi mi yapıyor? | JSON hata üretimi gibi bütünlüklü bir işi Direct route’a taşıyın. |
Ortak bir request’e zorunlu alan eklerken onu kullanan bütün işlemleri deneyin. “Yalnızca önizleme ekranında değiştirdim” demeniz, ortak modelin etkisini daraltmaz.
Yapı kuralıyla iş kuralını ayırın
quantity integer ve en az 1 olmalı: bu bir veri biçimi/kabul kuralıdır ve request şemasında gösterilebilir. Müşterinin limiti veya ürünün güncel stoğu yeterli olmalı: bu kontrol gerçek iş verisine ihtiyaç duyar ve route’ta yapılır.
Sipariş örneğinde miktarın 1–100 aralığı şemada, gösterim için seçilen 20 sınırı route’tadır. 0 gönderince 400, 21 gönderince 422 almanız bu ayrımı görünür kılar. Kendi projenizde rastgele iki farklı sınır koymayın; hangi sınırın neden var olduğunu açıklayın.
Bir default veya example tanımladığınızda eksik girdinin otomatik tamamlandığını varsaymayın. Örneği ve şema davranışını okuyun; eksik değer göndererek gerçek sonucu sınayın. Gerekli bir varsayılan değeri route’ta açıkça uygulayın.
Hatanın ardından yapılacak işi anlaşılır kılın
İstemci her hatada aynı işlemi yapmamalı. Miktar eksikse isteği düzeltir; müşteri bulunamıyorsa doğru kaydı seçer; kimlik doğrulama reddedildiyse credential veya yetkiyi inceler. Bu yüzden hatada durum kodu, kararlı iş kodu ve açıklama farklı işler görür.
ORDER_LIMIT uygulamanın karar verebildiği bir kod, “Preview supports at most 20 units.” ise insanın okuyacağı açıklamadır. Açıklamayı Türkçeleştirmek veya düzeltmek istemcinin kararını bozmamalıdır. Teknik exception metnini doğrudan müşteri mesajına çevirmek yerine, istemcinin düzeltebileceği şeyi anlatın; teşhis ayrıntısını izlemede inceleyin.
Bir 404 yanıtını yalnızca gövdedeki status alanında yazmayın. HTTP durumunu da ayarlayın. Aynı biçimde JSON gönderen bir route’un içerik türünü belirtin. Try it sonucunda durum, header ve gövdeyi birlikte okuyun.
Sözleşme, örnek ve gerçek yanıtı birlikte tutun
Route toplamı artık farklı hesaplıyor ama OpenAPI örneği eski sonucu gösteriyorsa kullanıcı Mock’ta başka, gerçek çağrıda başka sonuç görür. Bu fark bazen öğretici bir deneydir; yayımlanan sözleşmede ise açıklanması veya düzeltilmesi gerekir.
Bir response alanı eklerken üç noktayı kontrol edin: alan schema’da nasıl tarif ediliyor, route hangi değeri üretiyor, örnek hangi sonucu gösteriyor? Save, çalışan runtime’a uygulama ve gerçek çağrı ayrı adımlardır. Geliştirmede Save → Reload, kalıcı yayın için ilgili Git/build/deployment akışı kullanılır.
Yalnızca info.version değerini artırmak yeni URL veya ikinci çalışan API oluşturmaz. Farklı sürümler aynı anda kullanılacaksa yolları, çağıran uygulamaları ve dağıtımı ayrıca planlayın.
Tekrar gelen isteği baştan düşünün
Önizleme örneğini iki kez çağırmak iki sipariş oluşturmaz; çünkü yalnızca hesap yapar. Gerçek sipariş kaydeden bir POST’ta ise bağlantı koptuğunda istemci, işlemin tamamlanıp tamamlanmadığını bilemeyebilir. Aynı isteği yeniden göndermesi çift kayıt oluşturabilir.
Bir iş kimliğinin tekrarını nasıl tanıyacağınızı ve önceki sonucu nasıl döndüreceğinizi tasarlayın. OpenAPI’ye Idempotency-Key header’ı eklemek bunu kendiliğinden uygulamaz. Saklama ve tekrar kontrolü iş akışında gerekir. Veritabanı rehberindeki çift kayıt ve tekrar deneme örnekleri bu soruyu somutlaştırır.
Bir değişikliği altı çağrıyla değerlendirin
Her proje aynı test sayısına ihtiyaç duymaz. Yine de bir request modelini veya ortak hata akışını değiştirdiğinizde şu örnekler çoğu ilk sorunu görünür kılar:
- Normal istek: doğru iş sonucu ve HTTP durumu geliyor mu?
- Eksik zorunlu alan: hata doğru alanı veya üst nesneyi gösteriyor mu?
- Yanlış tür veya sınır:
"2",0, limitin hemen altı ve üstü nasıl davranıyor? - Biçimi doğru, bulunmayan kayıt: doğrulama geçip uygun iş hatası geliyor mu?
- Aynı modeli kullanan başka işlem: ortak değişiklik ona da doğru uygulanmış mı?
- Değişiklikten sonra aynı isteğin tekrarı: çalışan runtime yeni sürümü kullanıyor mu?
API’yi dış istemciye açtığınızda bu listeye geçerli, eksik ve yanlış kimlik doğrulama denemelerini gerçek yayın adresinde ekleyin. Running project iş mantığını denemeyi sağlar; yayın erişimini ayrıca doğrulayın.