20 Tem 2025·8 dk
API Evrimi ve Yapay Zeka Back-end'lerinde Geriye Dönük Uyumluluk
API'lerin nasıl güvenli evrildiğini öğrenin: sürümlendirme, uyumlu değişiklikler, migrasyon adımları, kaldırma politikası ve istemcileri bozmayan testler.
API'lerin nasıl güvenli evrildiğini öğrenin: sürümlendirme, uyumlu değişiklikler, migrasyon adımları, kaldırma politikası ve istemcileri bozmayan testler.
API evrimi, bir API gerçek istemciler tarafından kullanıldıktan sonra yapılan değişikliklerin sürekli sürecidir. Bu, alan eklemek, doğrulama kurallarını ayarlamak, performansı iyileştirmek veya yeni uç noktalar tanıtmak anlamına gelebilir. Gerçek kullanıcılar üretimde olduğunda önem kazanır; çünkü “küçük” bir değişiklik bir mobil uygulama sürümünü, bir entegrasyon betiğini veya bir ortak iş akışını bozabilir.
Bir değişiklik, mevcut istemciler herhangi bir güncelleme yapmadan çalışmaya devam ediyorsa geriye dönük uyumlu sayılır.
Örneğin, API'niz şu yanıtı döndürüyor olsun:
{ "id": "123", "status": "processing" }
Yeni, isteğe bağlı bir alan eklemek genellikle geriye dönük uyumludur:
{ "id": "123", "status": "processing", "estimatedSeconds": 12 }
Bilinmeyen alanları görmezden gelen eski istemciler çalışmaya devam eder. Buna karşılık, status'ı state olarak yeniden adlandırmak, bir alanın tipini değiştirmek (string → number) veya isteğe bağlı bir alanı zorunlu yapmak yaygın kırıcı değişikliklerdir.
AI tarafından oluşturulan bir backend sadece bir kod parçası değildir. Pratikte şunları içerir:
AI, sistemi hızlıca yeniden üretebildiği için API zaman içinde "sürüklenebilir"; bu yüzden değişiklikleri kasıtlı olarak yönetmezseniz sözleşme disiplinine ihtiyaç artar.
Bu, sohbetten tam uygulamalar ürettiğinizde daha da önem kazanır. Örneğin Koder.ai gibi bir platform, basit bir sohbette React (web), Go + PostgreSQL (backend) ve Flutter (mobil) kullanarak web, sunucu ve mobil uygulamalar oluşturabilir. Bu hız faydalıdır, ancak yeniden üretilen sürümlerin istemcilerin dayandığı davranışı kazara değiştirmemesi için sözleşme disiplini ve otomatik diff/testler daha önemlidir.
AI pek çok şeyi otomatikleştirebilir: OpenAPI spec'leri üretmek, boilerplate kodu güncellemek, güvenli varsayılanlar önermek ve hatta migrasyon adımlarını taslak hâline getirmek. Ancak kullanıcı sözleşmelerini etkileyen kararlar—hangi değişikliklere izin verileceği, hangi alanların kararlı olduğu, uç durumlar ve iş kuralları—için insan incelemesi hâlâ gereklidir. Amaç hız ve öngörülebilir davranıştır; sürpriz pahasına hız değil.
APİ'lerin nadiren tek bir "istemcisi" olur. Küçük bir üründe bile aynı uç noktalara bağımlı birden fazla tüketici olabilir:
Bir API bozulduğunda maliyet sadece geliştirici zamanı değildir. Mobil kullanıcılar eski sürümlerde haftalarca takılı kalabilir; bu da uzun kuyruklu hatalar ve destek biletleri doğurur. Ortaklar kesinti yaşayabilir, veri kaçırabilir veya kritik iş akışları durabilir—sözleşmesel veya itibara dair sonuçlar doğabilir. Dahili servisler sessizce başarısız olabilir ve temizlenmesi zor yığınlar oluşabilir (örneğin eksik olaylar veya tamamlanmamış kayıtlar).
AI tarafından oluşturulan backend'ler farklı bir zorluk getirir: kod hızlı ve sık değişebilir, bazen büyük diff'lerle, çünkü üretim çalışma kodu üretmeye odaklıdır—zaman içinde davranışı korumaya değil. Bu hız değerlidir ama aynı zamanda adını değiştirilmiş alanlar, farklı varsayılanlar, daha sıkı doğrulama veya yeni auth gereksinimleri gibi kazara kırıcı değişiklikler riskini artırır.
Bu yüzden geriye dönük uyumluluk kasıtlı bir ürün kararı olmalıdır, bir alışkanlık değil. Pratik yaklaşım, API'yi bir ürün arayüzü gibi ele alan tahmin edilebilir bir değişiklik süreci tanımlamaktır: yetenekler ekleyebilirsiniz, ancak mevcut istemcileri şaşırtmazsınız.
Yararlı bir zihni model, API sözleşmesini (ör. bir OpenAPI spec) istemcilerin güvenebileceği "gerçeklik kaynağı" olarak ele almaktır. Üretim sonra bir uygulama detayıdır: backend'i yeniden üretebilirsiniz, ama sözleşme—ve verdiği vaatler—bilinçli bir sürümleme ve iletişim olmadan değişmez.
AI sistemi backend kodunu hızlıca üretebilir veya değiştirebilirken, tek güvenilir çapa API sözleşmesidir: istemcilerin ne çağırabileceğini, ne göndermek zorunda olduklarını ve ne bekleyebileceklerini yazılı olarak tanımlayan belge.
Bir sözleşme, makine tarafından okunabilir bir spec olabilir:
Bu sözleşme dış tüketicilere verdiğiniz taahhüttür—uygulamanın arkasındaki implementasyon değişse bile.
Contract-first iş akışında, OpenAPI/GraphQL şemasını önce tasarlarsınız, sonra sunucu stub'ları üretip mantığı doldurursunuz. Bu genellikle uyumluluk açısından daha güvenlidir çünkü değişiklikler kasıtlı ve incelenebilir.
Code-first iş akışında, sözleşme kod anotasyonlarından veya çalışma zamanından türetilir. AI tarafından üretilen backend'ler genellikle varsayılan olarak code-first eğilimindedir; bu sorun değil—üretilen sözleşme bir çıktı olarak incelenmeli, göz ardı edilmemelidir.
Pratik bir hibrit: AI'ye kod değişikliği önerme izni verin, ancak aynı zamanda sözleşmeyi güncellemesini/yeniden üretmesini zorunlu kılın ve sözleşme diff'lerini ana değişiklik sinyali olarak kullanın.
API spec'lerinizi backend ile aynı repoda saklayın ve pull request üzerinden inceleyin. Basit bir kural: sözleşme değişikliği anlaşılmadan merge yok. Bu, geriye dönük uyumsuz düzenlemeleri üretime gitmeden önce görünür kılar.
Sapmayı azaltmak için sunucu stub'larını ve istemci SDK'larını aynı sözleşmeden üretin. Sözleşme güncellendiğinde her iki taraf da birlikte güncellensin—böylece AI tarafından üretilen implementasyonun istemcilerin beklemediği davranışları "icat etmesi" zorlaşır.
API sürümlendirme gelecekteki her değişikliği tahmin etmekle ilgili değildir—istemcilere backend'i iyileştirirken çalışmaya devam etmeleri için net, kararlı bir yol sağlamakla ilgilidir. Pratikte "en iyi" strateji, tüketicilerinizin hemen anlayabileceği ve ekibinizin tutarlı uygulayabileceği stratejidir.
URL sürümlendirme, sürümü yol içinde koyar: /v1/orders ve /v2/orders. Her istekte görünürdür, hata ayıklaması kolaydır ve caching/yönlendirme ile iyi çalışır.
Header sürümlendirme, URL'leri temiz tutar ve sürümü bir header'a taşır (örneğin Accept: application/vnd.myapi.v2+json). Zarif olabilir ama hata ayıklamada daha az belirgindir ve kopyala-yapıştır örneklerinde atlanabilir.
Query parametre sürümlendirme /orders?version=2 gibi bir yapı kullanır. Basittir, ancak istemciler veya proxy'ler query string'leri değiştirirse karışıklığa yol açabilir ve insanlar sürümleri karıştırmaya daha meyillidir.
Çoğu ekip için—özellikle istemci anlayışını basit tutmak istiyorsanız—URL sürümlendirmeyi varsayılan yapın. En az sürpriz yaratan yaklaşımdır, belgelemek kolaydır ve hangi sürümün çağrıldığını açıkça gösterir.
AI ile backend üretirken her sürümü ayrı bir "sözleşme + uygulama" birimi olarak ele alın. Güncellenmiş bir OpenAPI spec'ten yeni bir /v2 iskeleti oluşturup /v1'i olduğu gibi bırakabilirsiniz; iş mantığını mümkün olduğunca paylaşabilirsiniz. Bu, riski azaltır: mevcut istemciler çalışmaya devam eder, yeni istemciler ise kasıtlı olarak v2'yi benimser.
Sürümleme yalnızca dokümanlar güncel kaldığında işe yarar. Sürümlenmiş API dokümanları tutun, sürüme göre örnekleri uyumlu hâlde saklayın ve changelog yayınlayın: ne değişti, ne kullanımdan kalktı ve geçiş notları (tercihen yan yana istek/yanıt örnekleriyle).
AI tarafından üretilen backend güncellendiğinde uyumluluğu düşünmenin en güvenli yolu: “Mevcut bir istemci hiçbir değişiklik yapmadan hâlâ çalışacak mı?” Aşağıdaki kontrol listesini kullanarak değişiklikleri yayımlamadan önce sınıflandırın.
Bu değişiklikler genellikle mevcut istemcileri bozmadan yapılır çünkü istemcilerin zaten gönderdiği veya beklediği şeyi geçersiz kılmaz:
middleName veya metadata). İstemciler tam alan seti beklemiyorsa çalışmaya devam eder.Bunları kırıcı olarak değerlendirin:
nullable → non-nullable).İstemcileri tolerant reader olmaya teşvik edin: bilinmeyen alanları yoksaymak ve beklenmeyen enum değerlerini zarifçe ele almak. Bu, backend'in alan ekleyerek evrimleşmesine izin verirken istemcileri güncelleme zorunluluğunu azaltır.
Bir jeneratör kazara kırıcı değişiklikleri politika ile engelleyebilir:
API değişiklikleri istemcilerin gördüğü şeydir: istek/yanıt şekilleri, alan adları, doğrulama kuralları ve hata davranışı. Veritabanı değişiklikleri ise backend'in sakladığı şeydir: tablolar, kolonlar, index'ler, kısıtlar ve veri formatları. İlişkili ama aynı değildirler.
Yaygın hata, bir veritabanı migrasyonunu "sadece dahili" olarak ele almaktır. AI tarafından üretilen backend'lerde API katmanı genellikle şemadan (veya ona sıkı bağlı) üretilir, bu yüzden şema değişikliği sessizce bir API değişikliğine dönüşebilir. Bu, istemcileri etkilemeyi amaçlamadan kırılmalara yol açar.
Her adımda hem eski hem yeni kod yollarının çalışır durumda kalmasını sağlayan çok adımlı yaklaşımı kullanın:
Bu desen "büyük patlama" sürümlerinden kaçınır ve geri alma seçenekleri sunar.
Eski istemciler genellikle bir alanın isteğe bağlı veya kararlı anlamda olduğunu varsayar. Yeni, non-null bir kolon eklerken tercihlerinizi:
arasında yapın.
Dikkat: DB varsayılanı her zaman yardımcı olmayabilir eğer API serializer hala null döndürüyor veya doğrulama kurallarını değiştiriyorsa.
AI araçları migrasyon scriptleri taslağı oluşturabilir ve backfill önerileri sunabilir, ancak insan doğrulaması gereklidir: kısıtları doğrulayın, performansı (kilitler, index oluşturma) kontrol edin ve eski istemcilerin çalışmaya devam ettiğinden emin olmak için staging verisi üzerinde migrasyonları çalıştırın.
Feature flag'ler davranışı uç nokta şeklini değiştirmeden değiştirmenizi sağlar. AI tarafından oluşturulan backend'lerde iç mantık sıkça yeniden üretilebilir veya optimize edilebilir, ancak istemciler kararlı istek/yanıt biçimine güvenmeye devam etmelidir.
Büyük bir anahtar yerine, yeni kod yolunu kapalı gönderebilir, sonra kademeli olarak açabilirsiniz. Bir sorun çıktığında acil yeniden dağıtım yerine flag'i kapatabilirsiniz.
Pratik bir rollout planı genellikle üç tekniği birleştirir:
API'ler için kilit nokta, yanıtları sabit tutarken iç deneyler yapmaktır. Yeni model, yeni yönlendirme mantığı veya yeni DB sorgu planı gibi implementasyonları değiştirirken sözleşmenin vaat ettiği durum kodlarını, alan adlarını ve hata formatlarını koruyabilirsiniz. Yeni veri eklemeniz gerekirse, istemcilerin görmezden gelebileceği ekleyici alanları tercih edin.
POST /orders uç noktası şu anda phone'u pek çok formatta kabul ediyorsa ve siz E.164 formatını zorunlu kılmak istiyorsunuz, sıkı doğrulama istemcileri bozabilir.
Daha güvenli yaklaşım:
strict_phone_validation gibi bir flag'in arkasında daha sıkı validator gönderin.Bu desen, daha iyi veri kalitesine doğru ilerlerken geriye dönük uyumlu bir API'yi kazara kırmamanızı sağlar.
Deprecation, eski API davranışı için "nazik çıkış"tır: onu teşvik etmeyi kesersiniz, istemcilere erken uyarı verirsiniz ve ilerlemek için öngörülebilir bir yol sunarsınız. Sunsetting son adımdır: eski sürüm yayımlanmış bir tarihte kapatılır. AI tarafından oluşturulan backend'lerde uç noktalar ve şemalar hızlıca evrilebildiğinden, sıkı bir emekliye ayırma süreci güveni ve güvenliği korur.
API sözleşmesi düzeyinde semantik versiyonlamayı kullanın, sadece repoda değil:
Bu tanımı dokümanlarınızda bir kez koyun ve tutarlı uygulayın. Bu, AI destekli değişikliklerin "sessiz major" olmasını engeller.
Kullanıcıların plan yapabilmesi için varsayılan bir politika seçin ve ona bağlı kalın. Yaygın bir yaklaşım:
Emin değilseniz biraz daha uzun bir pencere seçin; sürümü kısa süre açık tutmanın maliyeti genellikle acil istemci migrasyonlarının maliyetinden düşüktür.
Herkes release notlarını okumadığı için birden fazla kanal kullanın:
Deprecation: true ve Sunset: Wed, 31 Jul 2026 00:00:00 GMT, ayrıca Link: /docs/api/v2/migration gibi metinler.Ayrıca changelog ve durum güncellemelerine deprecaton notları ekleyin ki satın alma ve operasyon ekipleri görsün.
Eski sürümü sunayt tarihinde çalıştırmayı kesin ve bilinçli kapatın—kazara bozma yoluyla değil.
Sunset'te:
410 Gone) ve en yeni sürüme ve geçiş rehberine işaret eden bir açıklama sağlayın.En önemlisi, emekliye ayırmayı sahipleri, izleme ve geri alma planı olan planlı bir değişiklik olarak ele alın. Bu disiplin, sık değişimleri istemcileri şaşırtmadan mümkün kılar.
AI tarafından üretilen kod hızlı değişebilir—bazen şaşırtıcı yerlerde. İstemcilerin çalışmaya devam etmesini sağlamanın en güvenli yolu, implementasyonu değil sözleşmeyi (dışarı vaat ettiklerinizi) test etmektir.
Pratik bir temel, önceki OpenAPI spec'i ile yeni üretileni karşılaştıran bir sözleşme testidir. "önce vs. sonra" kontrolü gibi davranır:
Pek çok ekip CI'de OpenAPI diff otomasyonu çalıştırır; böylece üretilen hiçbir değişiklik inceleme olmadan dağıtılamaz. Bu, prompt'lar, şablonlar veya model sürümleri değiştiğinde özellikle faydalıdır.
Tüketici odaklı sözleşme testi perspektifi ters çevirir: backend ekibinin API'yi istemcilerin nasıl kullandığını tahmin etmesi yerine, her istemci küçük bir beklenti seti (gönderdiği istekler ve güvendiği yanıtlar) paylaşır. Backend, sürümden önce bu beklentileri karşılamaya devam ettiğini kanıtlamalıdır.
Bu, birden fazla tüketici (web uygulaması, mobil uygulama, ortaklar) varsa ve her dağıtımı koordine etmeden güncelleme yapmak istiyorsanız iyi çalışır.
Aşağıdakileri kilitleyen regresyon testleri ekleyin:
Bir hata şeması yayımlıyorsanız, onu açıkça test edin—istemciler hataları beklenenden daha fazla parse ediyor olabilir.
OpenAPI diff kontrollerini, tüketici sözleşmelerini ve şekil/hata regresyon testlerini bir CI kapısında birleştirin. Üretilen bir değişiklik başarısız olursa, düzeltme genellikle prompt'u, üretim kurallarını veya bir uyumluluk katmanını ayarlamak olur—kullanıcılar fark etmeden önce.
İstemciler API ile entegre olduklarında genellikle hata mesajlarını okumazlar—hata şekline ve kodlarına tepki verirler. İnsan dostu bir mesajdaki yazım hatası can sıkıcıdır ama tolere edilebilir; durum kodu değişikliği, eksik alan veya yeniden adlandırılmış bir hata tanımlayıcısı ise geri kazanılabilir bir durumu kırılmış bir ödeme, başarısız bir senkronizasyon veya sonsuz yeniden deneme döngüsüne dönüştürebilir.
Tutarlı bir hata zarfı (JSON yapısı) ve istemcilerin güvenebileceği sabit tanımlayıcılar tutmayı hedefleyin. Örneğin { code, message, details, request_id } döndürüyorsanız, bu alanları yeni sürümde kaldırmayın veya yeniden adlandırmayın. message içeriğini iyileştirebilirsiniz ama code semantiğini sabit ve dokümante edilmiş tutun.
Zaten birden fazla format yayındaysa, "onu yerinde temizleme" dürtüsüne direnin. Bunun yerine, yeni formatı bir sürüm sınırının arkasında veya bir müzakere mekanizması ile (ör. Accept header) tanıtın ve eskisini desteklemeye devam edin.
Yeni hata kodları gerekli olabilir, ancak bunları istemcileri şaşırtmayacak şekilde ekleyin:
VALIDATION_ERROR ile başa çıkıyorsa, bunu aniden INVALID_FIELD ile değiştirmeyin.code döndürün ama geriye dönük uyumluluk için details içinde eski genelleyici koda dair ipuçları verin (veya eski koda map edin).message'ı göstermek gibi.Kesinlikle mevcut bir kodun anlamını değiştirmeyin. Eğer NOT_FOUND daha önce "kaynak yok" demekse, onu "erişim reddedildi" için kullanmayın (bu 403 olmalı).
Geriye dönük uyumluluk aynı isteğe aynı sonucu vermektir. Görünüşte küçük varsayılan değişiklikler bile istemcileri kırabilir.
Sayfalama: varsayılan limit, page_size veya cursor davranışını sürümlemeden değiştirmeyin. Sayfa tabanlıdan cursor tabanlıya geçiş kırıcıdır; her iki yolu da koruyun.
Sıralama: varsayılan sıralama kararlı olmalıdır. created_at desc'den relevance desc'e geçmek listelerin yeniden sıralanmasına ve UI varsayımlarının veya artımlı senkronizasyonun bozulmasına neden olabilir.
Filtreleme: örtük filtreleri değiştirmeyin (ör. varsayılan olarak “inactive” öğeleri dışlamak). Yeni davranış gerekiyorsa, açık bir flag ekleyin, örn. include_inactive=true veya status=all.
Bazı uyumluluk sorunları uç noktalardan ziyade yorumlamayla ilgilidir.
"9.99"'u 9.99'a (veya tersi) dönüştürmeyin.include_deleted=false veya send_email=true gibi varsayılanlar tersine çevrilmemeli. Değişiklik gerekiyorsa istemcinin yeni parametre ile opt-in yapmasını zorunlu kılın.AI tarafından oluşturulan backend'lerde model, yanıtları "iyileştirme" eğiliminde olabilir; bu yüzden bu davranışları açık sözleşmeler ve testlerle kilitleyin.
Geriye dönük uyumluluğu bir defa doğrulayıp unutmayın. AI tarafından üretilen backend'lerde davranış el yapımı sistemlerden daha hızlı değişebileceği için kim neyi kullanıyor ve bir güncellemenin istemcilere zarar verip vermediği gösteren geri bildirim döngülerine ihtiyacınız var.
Her isteğe açık bir API sürümü (yol: /v1/..., header: X-Api-Version veya müzakere edilen şema sürümü) etiketi koyun. Sonra sürüme göre segmentlenmiş metrikler toplayın:
Böylece örneğin /v1/orders trafikte sadece %5 görünür ama rollout sonrası hataların %70'ini oluşturuyorsa bunu fark edebilirsiniz.
API gateway veya uygulamanızı, istemcilerin gerçekten ne gönderdiğini ve hangi rotaları çağırdığını loglayacak şekilde instrument edin:
/v1/legacy-search)SDK'ları kontrol ediyorsanız, güncel olmayan entegrasyonları tespit etmek için hafif bir istemci tanımlayıcı + SDK sürüm header'ı ekleyin.
Hata arttığında cevaplamak isteyeceksiniz: “Hangi dağıtım davranışı değiştirdi?” Aşağıdakilerle pikleri ilişkilendirin:
Geri almaları sade tutun: her zaman önceki üretilmiş artifact'ı (container/image) yeniden dağıtabilin ve trafiği router üzerinden geri çevirin. Veri geri dönüşü gerektiren geri almalardan kaçının; şema değişiklikleri varsa additive DB migrasyonlarını tercih edin ki eski sürümler çalışmaya devam etsin.
Platformunuz environment snapshot'ları ve hızlı geri alma destekliyorsa bunları kullanın. Örneğin Koder.ai workflow'unda snapshot'lar ve rollback özellikleri bulunur; bu, “expand → migrate → contract” veritabanı değişiklikleri ve kademeli API rollouts ile doğal bir uyum sağlar.
AI tarafından üretilen backend'ler hızla değişebilir—yeni uç noktalar ortaya çıkar, modeller kayabilir, doğrulamalar sıkılaşabilir. İstemcileri kararlı tutmanın en güvenli yolu API değişikliklerini tek seferlik düzenlemeler gibi değil, küçük ve tekrarlanabilir bir sürüm süreci olarak ele almaktır.
Nedenini, hedeflenen davranışı ve kesin sözleşme etkisini (alanlar, tipler, zorunlu/isteğe bağlı, hata kodları) yazın.
Bunu uyumlu (güvenli) veya kırıcı (istemci değişikliği gerektirir) olarak işaretleyin. Emin değilseniz kırıcı sayın ve bir uyumluluk yolu tasarlayın.
Eski istemcileri nasıl destekleyeceğinize karar verin: alias'lar, dual-write/dual-read, varsayılan değerler, toleranslı parse etme veya yeni bir sürüm gibi.
Değişikliği feature flag'ler veya konfigürasyon ile ekleyin ki kademeli açıp kapatabilelim.
Otomatik sözleşme kontrolleri (OpenAPI diff kuralları) ve bilinen istemci istek/yanıt testleri çalıştırın.
Her sürüm şu bilgileri içermeli: güncellenmiş referans dokümanları /docs, ilgili migration notu ve değişikliğin uyumlu olup olmadığına dair kısa bir changelog girdisi.
Deprecation'ı duyurun, kalan kullanımı ölçün ve sunset penceresinden sonra kaldırın.
last_name'i family_name yapmak istiyorsanız:
family_name'i tercih edin.family_name döndürüp last_name'i alias olarak tutabilirsiniz.last_name'i kullanımdan kaldırılmış olarak işaretleyin ve kaldırma tarihini yayınlayın.Eğer teklifiniz plan bazlı destek veya uzun dönem sürüm desteği içeriyorsa, bunu açıkça /pricing üzerinde belirtin.
Geriye dönük uyumluluk, mevcut istemcilerin herhangi bir değişiklik yapmadan çalışmaya devam etmesi demektir. Pratikte genellikle şunlar yapılabilir:
Genellikle alanların yeniden adlandırılması/çıkarılması, tip değişiklikleri veya doğrulamanın sıkılaştırılması birilerinin bozulmasına yol açar ve bunlar yapılamaz.
Herhangi bir dağıtılmış istemcinin güncelleme gerektirmesine neden olacak değişiklikleri kırıcı olarak ele alın. Sık rastlanan kırıcı değişiklikler:
status → state)Bir API sözleşmesini sabit tutun, tipik olarak:
Sonrasında:
Bu, AI ile yeniden üretimin istemciye görünür şekilde davranışı gizlice değiştirmesini engeller.
Contract-first'te önce spec güncellenir, sonra kod üretilir/uygulanır. Code-first'te spec koddan türetilir.
AI iş akışları için pratik bir hibrit:
CI'de OpenAPI diff kontrolünü otomatikleştirin ve şu tip değişikliklerde build'leri başarısız sayın:
Birleştirmelere yalnızca (a) değişiklik uyumlu onaylandıysa veya (b) yeni bir major sürüme geçiliyorsa izin verin.
URL sürümlendirme (ör. /v1/orders, /v2/orders) genellikle en az sürpriz yapan yaklaşımdır:
Header veya query sürümlendirme de mümkün, ama hata ayıklamada ve örneklerde gözden kaçması daha olasıdır.
Bazı istemcilerin katı olduğunu varsayın. Daha güvenli kalıplar:
Eğer bir enum değerinin anlamını değiştirmek veya bir değeri kaldırmak gerekiyorsa, bunu yeni bir sürümün arkasında yapın.
“Expand → migrate → contract” yaklaşımını kullanın:
Bu, kesintisiz geçiş ve geri alma imkânı sağlar.
Feature flag'ler iç davranışı değiştirirken uç nokta şeklini sabit tutmanızı sağlar. Pratik bir dağıtım:
Bu, daha sıkı doğrulama veya performans yeniden yazımları için özellikle faydalıdır.
Kullanımı gözle görünür hale getirin ve zaman bağlı bir pencere belirleyin:
Deprecation: true, Sunset: Wed, 31 Jul 2026 00:00:00 GMT, Link: /docs/api/v2/migration)410 Gone