OpenAPI-first ve code-first API geliştirme: temel ödünleşmeler

Bu tartışmanın çözmeye çalıştığı gerçek sorun

OpenAPI-first ile code-first tartışması aslında tercih meselesi değil. Asıl amaç, bir API'nin söylediği ile gerçekte yaptığı arasındaki yavaş ayrışmayı önlemek.

OpenAPI-first, API sözleşmesini (endpoints, girişler, çıkışlar, hatalar) OpenAPI spesifikasyonunda yazarak başlamayı ve sonra sunucu ile istemcileri buna göre inşa etmeyi ifade eder. Code-first ise önce kodda API'yi yazıp, sonra uygulamadan OpenAPI spec ve dokümanları üretmeyi ifade eder.

Ekipler bu konuda tartışır çünkü acı genellikle sonra çıkar; genellikle küçük bir backend değişikliğinden sonra kırılan bir istemci uygulaması, sunucunun artık sahip olmadığı davranışı anlatan dokümanlar, uç noktalarda tutarsız doğrulama kuralları, insanların tahmin etmesini gerektiren belirsiz 400 hataları ve "dün çalışıyordu" ile başlayan destek talepleri şeklinde görülür.

Basit bir örnek: mobil uygulama phoneNumber gönderiyor, ama backend alan adını phone olarak değiştirdi. Sunucu genel bir 400 döndürüyor. Dokümanlar hâlâ phoneNumber diyor. Kullanıcı "Bad Request" görüyor ve geliştirici loglarda kazı yapmak zorunda kalıyor.

Gerçek soru şu: API değişirken sözleşme, çalışma zamanı davranışı ve istemci beklentilerini nasıl aynı hatta tutarsınız?

Bu karşılaştırma günlük işi etkileyen dört çıktıya odaklanıyor: hız (şimdi hangi yaklaşım hızlıdır ve zamanla hangisi hızlı kalır), tutarlılık (sözleşme, doküman ve çalışma zamanı davranışının eşleşmesi), istemci üretimi (bir spec ne zaman zaman kazandırır ve hataları önler) ve doğrulama hataları ("geçersiz giriş"i insanların harekete geçebileceği mesajlara nasıl dönüştürürsünüz).

İki iş akışı: OpenAPI-first ve code-first genelde nasıl çalışır

OpenAPI-first sözleşme ile başlar. Kimse endpoint kodunu yazmadan önce ekip yolları, istek ve yanıt şekillerini, durum kodlarını ve hata formatlarını üzerinde anlaşır. Fikir basit: API'nin nasıl görünmesi gerektiğine karar verin, sonra onu o şekilde inşa edin.

Tipik bir OpenAPI-first akışı:

• OpenAPI spesifikasyonunu taslağı (endpoints, şemalar, yetkilendirme, hatalar)
• Backend, frontend ve QA ile gözden geçirin
• Stub'lar üretin veya spesifikasyonu tek gerçek kaynak olarak paylaşın
• Sunucuyu buna uygun şekilde uygulayın
• İstekleri ve yanıtları sözleşmeye karşı doğrulayın (testler veya middleware)

Code-first sıralamayı tersine çevirir. Endpoint'leri kodda inşa edersiniz, sonra bir araç bunlardan OpenAPI belgesi üretebilsin diye açıklamalar veya yorumlar eklersiniz. Deneysel aşamada mantıksal değişiklikler ve rotaları ayrı bir spesifikasyon güncellemeden hemen değiştirebildiğiniz için bu daha hızlı gelebilir.

Tipik code-first akışı:

• Endpoint'leri ve modelleri kodda uygulayın
• Şemalar, parametreler ve yanıtlar için açıklamalar ekleyin
• Kod tabanından OpenAPI spesifikasyonunu üretin
• Çıktıyı (genellikle açıklamaları düzelterek) ayarlayın
• Üretilen spec'i dokümanlar ve istemci üretimi için kullanın

Nerede sürüklenme (drift) oluşacağı kullanılan iş akışına bağlıdır. OpenAPI-first'te sürüklenme, spesifikasyon bir kere taslak olarak yazılıp sonrasında güncellenmez olduğunda ortaya çıkar. Code-first'te sürüklenme, kod değiştiğinde ama açıklamalar güncellenmediğinde meydana gelir; böylece üretilen spec görünüşte doğru olsa da gerçek davranış (durum kodları, zorunlu alanlar, kenar durumlar) sessizce farklılaşmış olur.

Basit bir kural: contract-first, spesifikasyon yok sayıldığında sürüklenir; code-first ise dokümantasyon sonradan düşünülünce sürüklenir.

Hız: şimdi ne hızlı geliyor vs sonra ne hızlı kalır

Hız tek bir şey değildir. "Bir sonraki değişikliği ne kadar hızlı gönderebiliriz" ile "altı ay sonra değişiklik yapmaya ne kadar hızlı devam edebiliriz" farklıdır. İki yaklaşım genelde hangi aşamada hızlı hissettireceğini takas eder.

Erken dönemde code-first daha hızlı gelebilir. Bir alan eklersiniz, uygulamayı çalıştırırsınız ve işler. API hâlâ hareketli bir hedefken bu geri bildirim döngüsü çok değerlidir. Maliyet, diğer insanlar API'ye güvenmeye başladığında ortaya çıkar: mobil, web, dahili araçlar, partnerler ve QA.

OpenAPI-first ilk günde daha yavaş hissedilebilir çünkü endpoint oluşmadan önce sözleşmeyi yazarsınız. Kazanç daha az yeniden çalışmadır. Bir alan adı değiştiğinde, değişiklik görünür ve incelemeye açık olur, böylece istemciler bozulmadan önce fark edilir.

Uzun vadeli hız çoğunlukla tekrar işten kaçınmakla ilgilidir: ekipler arası daha az yanlış anlama, tutarsız davranıştan kaynaklanan daha az QA döngüsü, sözleşmenin net bir başlangıç noktası olması sayesinde daha hızlı onboarding ve değişikliklerin açık şekilde onaylanması.

Ekipleri yavaşlatan en büyük şey kod yazmak değil; yeniden çalışmadır: istemcileri yeniden yapmak, testleri yeniden yazmak, dokümanları güncellemek ve belirsiz davranıştan doğan destek taleplerine cevap vermek.

Eğer dahili bir araç ve bir mobil uygulamayı paralel inşa ediyorsanız, contract-first her iki ekibin aynı anda ilerlemesine izin verebilir. Ve eğer gereksinimler değiştiğinde kodu yeniden üreten bir platform kullanıyorsanız (örneğin AppMaster), aynı prensip uygulama evrildikçe eski kararları taşımamanıza yardım eder.

Tutarlılık: sözleşme, doküman ve davranışı aynı tutmak

Çoğu API sorunu eksik özelliklerle ilgili değildir. Sorun uyuşmazlıklardır: doküman bir şeyi söyler, sunucu başka bir şey yapar ve istemciler fark etmesi zor şekilde bozulur.

Ana fark "gerçek kaynak"tadır. Contract-first akışta spesifikasyon referanstır ve diğer her şey ona uymalıdır. Code-first akışta çalışan sunucu referanstır ve spec ile dokümanlar genellikle sonradan gelir.

İsimlendirme, tipler ve zorunlu alanlar sürüklenmenin ilk görüldüğü yerlerdir. Bir alan kodda yeniden adlandırılır ama spec'te değil. Bir boolean, bir istemci "true" gönderdiği için string olur. Bir alan isteğe bağlı iken zorunlu hale gelir ve eski istemciler eski şekli göndermeye devam eder. Her değişiklik küçük görünür; birlikte birikince sürekli bir destek yükü oluştururlar.

Tutarlılığı korumanın pratik yolu, asla ayrılmaması gerekenleri belirleyip iş akışınızda bunu zorunlu kılmaktır:

• İstekler ve yanıtlar için tek bir canonical şema kullanın (zorunlu alanlar ve formatlar dahil).
• Kırıcı değişiklikleri kasıtlı olarak versiyonlayın. Alan anlamını sessizce değiştirmeyin.
• İsimlendirme kurallarında (snake_case vs camelCase) anlaşın ve her yerde uygulayın.
• Örnekleri sadece doküman olarak değil, çalıştırılabilir test vakaları olarak değerlendirin.
• Uyuşmazlıkların hızlıca yakalanması için CI'de sözleşme kontrolleri ekleyin.

Örnekler ekstra dikkat gerektirir çünkü insanlar onları kopyalar. Bir örnek eksik zorunlu alan gösteriyorsa, gerçek trafiğiniz eksik alanlarla gelir.

İstemci üretimi: OpenAPI'nin en çok fayda sağladığı durumlar

Üretilen istemciler, aynı API'yi birden fazla ekip (veya uygulama) tükettiğinde en çok önemlidir. Bu noktada tartışma zevk meselesi olmaktan çıkar ve zaman kazandırmaya başlar.

Neler üretebilirsiniz (ve neden faydalı)

Sağlam bir OpenAPI sözleşmesinden sadece doküman değil daha fazla çıktı üretebilirsiniz. Yaygın çıktılar arasında hataları erken yakalayan tipli modeller, web ve mobil için istemci SDK'ları (metotlar, tipler, auth hook'ları), implementasyonun hizalanması için server stub'ları, QA ve destek için test fixture'ları ve örnek payload'lar ve frontend çalışmalarının backend tamamlanmadan başlayabilmesi için mock sunucular vardır.

Bu en hızlı geri dönüşü bir web uygulaması, bir mobil uygulama ve belki bir dahili araç aynı endpoint'leri çağırdığında verir. Küçük bir sözleşme değişikliği her yerde yeniden üretilebilir; elle yeniden uygulamaya gerek kalmaz.

Üretilen istemciler, ağır özelleştirme (özgün auth akışları, retry'ler, çevrimdışı önbellekleme, dosya yüklemeleri) gerektiğinde veya jeneratör ekibinizin beğenmediği kodu üretiyorsa sorun çıkarabilir. Yaygın bir uzlaşma, çekirdek tipleri ve düşük seviye istemciyi üretip, uygulamanızın kullandığı ince bir elle yazılmış katmanla sarmaktır.

Üretilen istemcilerin sessizce bozulmasını önleme

Mobil ve frontend uygulamalar sürpriz değişikliklerden nefret eder. "Dün derlendi" hatalarını önlemek için:

• Sözleşmeyi versiyonlanmış bir artefakt olarak ele alın ve değişiklikleri kod gibi inceleyin.
• Kırıcı değişiklikler için CI kontrolleri ekleyin (kaldırılan alanlar, tip değişiklikleri).
• Katkı olarak eklemeyi tercih edin (yeni isteğe bağlı alanlar) ve kaldırmadan önce deprecate edin.
• Hata yanıtlarını tutarlı tutun, böylece istemciler onları öngörülebilir şekilde işleyebilir.

Eğer operasyon ekibiniz bir web yönetim paneli kullanıyor ve saha personeliniz native bir uygulama kullanıyorsa, aynı OpenAPI dosyasından Kotlin/Swift modelleri üretmek alan adlarının ve eksik enum'ların uyuşmasını önler.

Doğrulama hataları: "400"'ü kullanıcıların anlayacağı hale getirmek

Çoğu "400 Bad Request" yanıtı kötü değildir. Bunlar normal doğrulama hatalarıdır: zorunlu bir alan eksik, bir sayı metin olarak gönderilmiş veya bir tarih yanlış formatta olabilir. Sorun, ham doğrulama çıktısının genellikle geliştirici notu gibi okunması; bir insanın düzeltebileceği şekilde olmamasıdır.

En çok destek bileti üreten hatalar genellikle zorunlu alan eksikliği, yanlış tipler, kötü formatlar (tarih, UUID, telefon, para birimi), aralık dışı değerler ve kabul edilmeyen değerlerdir (örneğin kabul listesinde olmayan bir durum).

Her iki iş akışı da aynı sonuca yol açabilir: API neyin yanlış olduğunu bilir, ancak istemci belirsiz bir "invalid payload" mesajı alır. Bunu düzeltmek iş akışından çok açık bir hata şekli ve tutarlı eşleme kuralları benimsemekle ilgilidir.

Basit bir desen: yanıtı tutarlı tutun ve her hatayı eyleme geçirilebilir yapın. Döndürün: (1) hangi alanın yanlış olduğu, (2) neden yanlış olduğu ve (3) nasıl düzelteceği.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Please fix the highlighted fields.",
    "details": [
      {
        "field": "email",
        "rule": "format",
        "message": "Enter a valid email address."
      },
      {
        "field": "age",
        "rule": "min",
        "message": "Age must be 18 or older."
      }
    ]
  }
}

Bu aynı zamanda UI formlarına da düzgün eşler: alanı vurgula, mesajı yanında göster ve yanlış bir şey kaçıranlar için kısa bir üst mesaj tut. Anahtar nokta, içsel ifadeleri ("failed schema validation" gibi) sızdırmamak ve kullanıcıya neyi değiştirebileceğini söyleyecek bir dil kullanmaktır.

Nerede doğrulama yapmalı ve çift kurallardan nasıl kaçınılır

Doğrulama en iyi şekilde her katmanın net bir işi olduğu durumlarda çalışır. Her katman her kuralı uygulamaya çalışırsa, çift iş, kafa karıştırıcı hatalar ve web, mobil ve backend arasında sürüklenen kurallar elde edersiniz.

Pratik bir ayrım şöyle görünür:

• Edge (API gateway veya istek işleyici): şekil ve tipleri doğrulayın (eksik alanlar, yanlış formatlar, enum değerleri). Bu kısım OpenAPI şemasının iyi uyduğu yerdir.
• Servis katmanı (iş mantığı): gerçek kuralları doğrulayın (izinler, durum geçişleri, "bitiş tarihi başlangıç tarihinden sonra olmalı", "indirim yalnızca aktif müşteriler için").
• Veritabanı: asla ihlal edilmemesi gerekenleri zorunlu kılın (unique constraint'ler, foreign key, not-null). Veritabanı hatalarını birincil kullanıcı deneyimi değil, güvenlik ağı olarak görün.

Web ve mobil arasında aynı kuralları tutmak için bir sözleşme ve tek bir hata formatı kullanın. İstemciler hızlı kontroller (zorunlu alanlar gibi) yapıyor olsa bile nihai yargıç olarak API'ye güvenmelidir. Böylece bir kural değişti diye mobil güncellemesi gerektiği için zincirleme güncellemeler olmaz.

Basit bir örnek: API'niz phone alanını E.164 formatında istiyor. Edge tüm istemciler için kötü formatları tutarlı şekilde reddedebilir. Ama "telefon günde bir kez değiştirilebilir" gibi bir kural kullanıcı geçmişine bağlı olduğu için servis katmanında olmalıdır.

Ne kaydedilmeli vs kullanıcıya ne gösterilmeli

Geliştiriciler için debug edebilmek adına yeterince log tutun: request id, user id (varsa), endpoint, doğrulama kuralı kodu, alan adı ve ham exception. Kullanıcılar için kısa ve eyleme geçirilebilir tutun: hangi alan başarısız oldu, neyi düzeltmeli ve (güvenliyse) bir örnek. İç tablo adları, stack trace'ler veya "kullanıcı rol X'te değil" gibi politika detaylarını göstermeyin.

Adım adım: bir yaklaşım seçmek ve uygulamak

Eğer ekip iki yaklaşım arasında tartışmayı sürdürüyor ise, tüm sistemi birden karar vermeye çalışmayın. Küçük, düşük riskli bir dilim seçin ve gerçek yapın. Bir pilottan öğreneceğiniz şey haftalarca süren görüşlerden daha fazladır.

Dar bir kapsamla başlayın: bir kaynak ve gerçekten kullanılan 1–3 endpoint (örneğin "ticket oluştur", "ticket listele", "durum güncelle") seçin. Üretime yakın ama rotayı değiştirebileceğiniz kadar küçük tutun.

Pratik bir rollout planı

1. Pilotu seçin ve "bitti"nin ne demek olduğunu tanımlayın (endpoints, auth ve ana başarı/başarısızlık senaryoları).

2. OpenAPI-first seçerseniz, server kodunu yazmadan önce şemaları, örnekleri ve standart hata şeklini yazın. Spesifikasyonu ortak anlaşma olarak değerlendirin.

3. Code-first seçerseniz, önce handler'ları oluşturun, spec'i dışa aktarın, sonra okunabilir bir sözleşme gibi görünene kadar (isimler, açıklamalar, örnekler, hata yanıtları) temizleyin.

4. Değişikliklerin kasıtlı olmasını sağlamak için sözleşme kontrolleri ekleyin: spec geri uyumluluğunu bozan değişikliklerde build'i başarısız kılın veya üretilen istemciler ile sözleşme arasında sürüklenme varsa yakalayın.

5. Bunu gerçek bir istemciye (bir web UI ya da mobil uygulama) açın, sürtünme noktalarını toplayın ve kurallarınızı güncelleyin.

Eğer AppMaster gibi no-code bir platform kullanıyorsanız, pilot daha da küçük olabilir: veriyi modelleyin, endpoint'leri tanımlayın ve aynı sözleşmeyi hem web yönetim ekranı hem de mobil görünüm için kullanın. Araç mücadeleyi belirlemez; önemli olan alışkanlıktır: tek bir gerçek kaynak, her değişiklikte test edilen ve gerçek payload'lara uygun örnekler.

Yavaşlamalara ve destek ticket'larına yol açan yaygın hatalar

Çoğu ekip "yanlış tarafı" seçtiği için başarısız olmaz. Başarısız olma nedeni, sözleşmeyi ve çalışma zamanını iki ayrı dünya gibi görüp sonra bunları uzlaştırmak için haftalar harcamaktır.

Klasik tuzaklardan biri OpenAPI dosyasını "güzel doküman" olarak yazmak ama onu zorunlu kılmamaktır. Spec sürüklenir, istemciler yanlış kaynaktan üretilir ve QA geç fark eder. Eğer bir sözleşme yayımlıyorsanız, onu test edilebilir yapın: istekleri ve yanıtları ona karşı doğrulayın veya davranışı hizalamak için server stub'ları üretin.

Diğer bir destek bileti fabrikası, versiyon kuralları olmadan istemci üretmektir. Mobil uygulamalar veya partner istemciler üretilen SDK'nın en yeni sürümüne otomatik güncelleniyorsa, küçük bir değişiklik (alan adını değiştirmek gibi) sessiz kırılmalara dönüşür. İstemci sürümlerini sabitleyin, net bir değişiklik politikası yayınlayın ve kırıcı değişiklikleri kasıtlı sürümler olarak ele alın.

Hata yönetimi küçük tutarsızlıkların büyük maliyetlere dönüştüğü yerdir. Eğer her endpoint farklı bir 400 şekli döndürüyorsa, frontend bir sürü tekil ayrıştırıcıya ve genel "Bir şeyler yanlış gitti" mesajına mahkum olur. Hataları standartlaştırın ki istemciler yararlı metinleri güvenilir şekilde gösterebilsin.

Çoğu yavaşlamayı önleyecek hızlı kontroller:

• Tek bir gerçek kaynak tutun: ya spec'ten kod üretin, ya koddan spec üretin ve her zaman eşleşip eşleşmediklerini doğrulayın.
• Üretilen istemcileri bir API sürümüne sabitleyin ve hangi değişikliklerin kırıcı sayıldığını belgeleyin.
• Her yerde aynı hata formatını kullanın (aynı alanlar, aynı anlam) ve stabil bir hata kodu ekleyin.
• Zor alanlar için örnekler ekleyin (tarih formatları, enum'lar, iç içe nesneler), sadece tip tanımlarını bırakmayın.
• Sınırda doğrulama yapın (gateway veya controller), böylece iş mantığı girdilerin temiz olduğunu varsayabilir.

Yön seçmeden önce hızlı kontroller

Bir yön seçmeden önce, ekibinizdeki gerçek sürtünme noktalarını açığa çıkaracak birkaç küçük kontrol yapın.

Basit bir hazır olma kontrol listesi

Bir temsilci endpoint seçin (istek gövdesi, doğrulama kuralları, birkaç hata durumu) ve şu sorulara "evet" yanıtı verebildiğinize emin olun:

• Sözleşme için atanmış bir sahibi var mı ve değişiklikler yayınlanmadan önce net bir gözden geçirme adımı var mı?
• Hata yanıtları uç noktalar arasında aynı görünüyor ve davranıyor mu: aynı JSON şekli, öngörülebilir hata kodları ve teknik olmayan bir kullanıcının harekete geçebileceği mesajlar mı?
• Sözleşmeden bir istemci üretebiliyor ve onu gerçek bir UI ekranında el tipi düzenleme yapmadan kullanabiliyor musunuz?
• Kırıcı değişiklikler dağıtımdan önce yakalanıyor mu (CI'de contract diff veya yanıtların şemaya uymadığını tespit eden testler)?

Sahiplik ve gözden geçirme konusunda tökezlerseniz, zamanla "neredeyse doğru" API'ler yayınlarsınız. Hata şekilleri konusunda tökezlerseniz, destek biletleri yığılır çünkü kullanıcılar sadece "400 Bad Request" görürler, "E-posta eksik" veya "Bitiş tarihi başlangıçtan sonra olmalı" yerine.

Pratik bir test: bir form ekranı alın (örneğin müşteri oluşturma) ve kasıtlı olarak üç hatalı girdi submit edin. Eğer bu doğrulama hatalarını özel durum kodu yazmadan, alan seviyesinde net mesajlara dönüştürebiliyorsanız, ölçeklenebilir bir yaklaşıma yakınsınız demektir.

Örnek senaryo: dahili araç + mobil uygulama, aynı API

Küçük bir ekip önce operasyonlar için bir dahili admin aracı, birkaç ay sonra saha personeli için bir mobil uygulama inşa ediyor. Her ikisi aynı API'yi kullanıyor: iş emirleri oluşturma, durum güncelleme, fotoğraf ekleme.

Code-first yaklaşımla, admin aracı genelde erken çalışır çünkü web UI ve backend birlikte değişir. Sorun mobil uygulama daha sonra yayınlandığında ortaya çıkar. O zamana kadar endpoint'ler sürüklenmiştir: bir alan yeniden adlandırılmış, bir enum değeri değişmiş ve bir endpoint önce "opsiyonel" olan bir parametreyi zorunlu hale getirmiştir. Mobil ekip bu uyuşmazlıkları genelde geç keşfeder, çoğunlukla rastgele 400'ler şeklinde, ve destek talepleri "Bir şeyler yanlış gitti" mesajları ile dolar.

Contract-first tasarımda hem admin web hem de mobil uygulama başından itibaren aynı şekillere, isimlere ve kurallara güvenebilir. Implementasyon detayları değişse bile sözleşme ortak referans olarak kalır. İstemci üretimi de daha çok değer kazandırır: mobil uygulama tipli istekleri ve modelleri elle yazmak yerine aynı OpenAPI dosyasından üretebilir.

Doğrulama kullanıcıların en çok hissettiği farktır. Mobil uygulama ülke kodu olmadan telefon gönderdiğini düşünün. Ham bir "400 Bad Request" yanıtı işe yaramaz. Kullanıcı dostu bir hata yanıtı platformlar arasında tutarlı olabilir, örneğin:

• code: INVALID_FIELD
• field: phone
• message: Enter a phone number with country code (example: +14155552671).
• hint: Add your country prefix, then retry.

Bu tek değişiklik, bir backend kuralını gerçek bir kişi için açık bir sonraki adıma çevirir; ister admin araçta olsun ister mobil uygulamada.

Sonraki adımlar: bir pilot seçin, hataları standartlaştırın ve güvenle inşa edin

Pratik bir kural: API birden fazla ekip tarafından paylaşılıyorsa veya birden fazla istemciyi desteklemesi gerekiyorsa OpenAPI-first seçin. Tüm sunucu ve istemciler tek ekip tarafından yönetiliyorsa ve API günlük olarak değişiyorsa code-first seçin; ama yine de koddan bir OpenAPI spec üretin ve bunu gözden geçirin ki sözleşmeyi kaybetmeyin.

Sözleşmenin nerede yaşadığını ve nasıl gözden geçirileceğini kararlaştırın. En basit düzenleme, OpenAPI dosyasını backend ile aynı repoda tutup her değişiklik incelemesinde zorunlu kılmaktır. Ona net bir sahip verin (çoğunlukla API sahibi veya tech lead) ve uygulamaları bozabilecek değişikliklerde en az bir istemci geliştiricisini incelemeye dahil edin.

Eğer hızlı ilerleyip her parçayı elle kodlamak istemiyorsanız, contract-driven yaklaşım no-code platformlarla da uyumludur. Örneğin AppMaster (appmaster.io) backend kodu ve web/mobil uygulamaları aynı temel modelden üretebilir; bu da API davranışı ve UI beklentilerini gereksinimler değiştikçe hizalı tutmayı kolaylaştırır.

Küçük, gerçek bir pilot ile ilerleyin, sonra genişletin:

• Gerçek kullanıcıları olan 2–5 endpoint ve en az bir istemci (web veya mobil) seçin.
• Hata yanıtlarını standartlaştırın ki bir "400" net alan mesajlarına dönüşsün (hangi alan başarısız oldu ve nasıl düzeltilecek).
• İş akışınıza sözleşme kontrolleri ekleyin (kırıcı değişiklikler için diff kontrolleri, temel linting ve yanıtların sözleşmeye uyduğunu doğrulayan testler).

Bu üçü iyi yaptığınızda, API'nin geri kalanı inşa edilmesi, belgelenmesi ve desteklenmesi daha kolay hale gelir.