API, Entegrasyon ve Kurumsal Sistemler
OpenAPI ile API Sözleşmesi Tasarımı ve Tutarlı Arayüzler
OpenAPI tanımını yalnızca dokümantasyon değil, ekiplerin ortak sözleşmesi olarak kullanın. Uç noktaları, veri şemalarını, hata yanıtlarını ve test beklentilerini geliştirmeden önce netleştirin.
API sözleşmesini geliştirmeden önce tasarlayın
Bir API çalışıyor olabilir; ancak onu kullanan ekipler aynı davranışı beklemiyorsa entegrasyon yine sorun çıkarır. Mobil uygulama bir alanın her yanıtta bulunacağını varsayarken servis bu alanı yalnızca belirli durumlarda gönderebilir. API sözleşmesi, hangi isteğin kabul edildiğini, hangi yanıtın döndüğünü ve başarısızlığın nasıl ifade edildiğini uygulama koduna geçmeden önce ortak bir karara dönüştürür.
OpenAPI, HTTP tabanlı arayüzü makine tarafından işlenebilir bir tanımla anlatır. Uç noktalar, parametreler, istek gövdeleri, yanıtlar ve güvenlik gereksinimleri aynı belgede toplanır. Bu tanım; dokümantasyon, istemci kodu üretimi, sahte servisler ve doğrulama araçları için ortak bir başlangıç noktası olabilir. Seçilen araçların kullanılan OpenAPI sürümünü desteklediği ayrıca kontrol edilmelidir.
Belgeyi geliştirme sonunda hazırlanan bir çıktı olarak görmeyin. Servis, web, mobil ve test ekipleri sözleşmeyi birlikte değerlendirmelidir. Kod değiştiğinde tanım ve testler de gözden geçirilmezse belge gerçek davranıştan uzaklaşabilir. Amaç ayrıntılı bir dosya üretmek değil, ekiplerin aynı beklentiyle geliştirme yapmasını sağlamaktır. Bu nedenle sözleşme incelemesi, teknik doğrulamanın yanında tüketici beklentilerini de kapsamalıdır.
Öne çıkanlar
Ortak sözleşmenin kapsamını belirleyin
OpenAPI tanımını hazırlamadan önce API’nin hangi ihtiyacı karşıladığını ve kimler tarafından kullanılacağını netleştirin. Kurum içindeki bir yönetim ekranıyla iş ortaklarına açılan bir arayüz aynı beklentilere sahip olmayabilir. Kaynakları ve alanları seçerken veritabanı yapısını doğrudan dışarı taşımak yerine tüketicinin iş akışını esas alın. Yönetim ekranlarının yanında arka plan görevlerini, raporlama süreçlerini ve dış sistemleri de değerlendirin. Belirsiz noktaları varsayımla kapatmak yerine açık sorular olarak kaydedin. Silinen bir kaynağın tekrar sorgulanması veya güncellemede gönderilmeyen alanların korunması gibi davranışları geliştirmeden önce karara bağlayın. Kararların sahibini ve gerekçesini kısa notlarla belirtmek, sonraki değişikliklerin etkisini değerlendirmeyi kolaylaştırır. İş kurallarıyla teknik temsil arasındaki ayrım da bu aşamada açıklığa kavuşmalıdır. Bir kaydı hangi sistemin yönettiğiyle hangi uygulamaların görüntülediği farklı konulardır. Bu ayrımı baştan yapmak, güncelleme ve doğrulama sorumluluklarının sistemler arasında belirsiz kalmasını önler. Kapsam dışında bırakılan işlemleri de açıkça belirtin; tüketiciler belgede yer almayan davranışları destekleniyor varsaymasın. Böylece ilk kullanım senaryosu, diğer entegrasyonların ihtiyaçlarını gölgelememiş olur.
Tüketici ve kullanım senaryosu
İstemcilerin yapacağı işlemleri, ihtiyaç duyduğu verileri ve karşılaşabileceği başarısızlıkları yazın.
Sahiplik ve adlandırma
Kaynakların sorumlusunu belirleyin; aynı iş kavramı için uç noktalar arasında tutarlı adlar kullanın.
Uygulama süreci
Uç noktaların işlem davranışlarını netleştirin
Bir uç noktanın adresini belirlemek sözleşmeyi tamamlamaz. HTTP yöntemi, parametrelerin konumu, içerik türü ve beklenen sonuç birlikte tasarlanmalıdır. Sipariş oluşturulduğunda yanıt yalnızca bir mesaj mı döndürecek, yoksa oluşturulan kaynağı mı içerecek? İşlem hemen tamamlanmıyorsa istemci sonucu nasıl takip edecek? İsteğin kabul edilmesiyle bütün iş sürecinin tamamlanması aynı anlama gelmez. Yan etkileri de açıklayın. Sipariş oluşturmak stok ayırıyor veya başka bir sisteme aktarım başlatıyorsa başarı yanıtının neyi doğruladığı bilinmelidir. Filtrenin sonuç üretmediği, sayfanın sonuna gelindiği ve kaynağın artık mevcut olmadığı durumları örnekleyin. İlişkili uç noktalar aynı kuralları izlediğinde istemcinin her işlem için ayrı bir entegrasyon mantığı geliştirmesi gerekmez. Asenkron işlemlerde takip bilgisi, ara durumlar ve nihai sonuç arasındaki ilişki anlaşılır olmalıdır. Başarısızlığın hangi aşamada bildirileceğini ve istemcinin hangi işlemi yapabileceğini yazın. Benzer işlemler farklı davranıyorsa bu farkı yalnızca örneklerde göstermeyin; işlem açıklamasında gerekçesiyle birlikte belirtin. Böylece tüketici ekipler başarı yanıtını olduğundan daha kapsamlı yorumlamaz.
- 01
Yöntem ve parametreler
İşlemin anlamını, yol ve sorgu parametrelerini, varsayılanları ve geçersiz değerlerin sonucunu tanımlayın.
- 02
Yanıt kapsamı
Başarı ve hata yanıtlarını içerik türleriyle belirtin; işlemler için benzersiz ve kararlı operationId değerleri kullanın.
Karşılaştırma
Eksik alan, boş değer ve null ayrımını koruyun
Alan gönderilmemiş: varlık kuralı değerlendirilir.
Alan null: değer kuralı değerlendirilir.
Boş metin, uzunluk kuralıyla sınırlandırılabilir.
Boş dizi, öğe sayısı kuralıyla sınırlandırılabilir.
Kontrol listesi
Şemanın ötesindeki davranış kurallarını açıklayın
Veri tipleri doğru olsa bile API davranışı belirsiz kalabilir. OpenAPI’nin yapısal alanlarıyla ifade edilemeyen iş kurallarını işlem açıklamalarında ve tasarım notlarında belirtin. Bir şema doğrulayıcı, kullanıcının belirli bir kaydı değiştirmeye yetkili olduğunu tek başına kanıtlamaz. Örnek yanıtlar da uygulamanın her koşulda aynı davranışı göstereceğini garanti etmez. “Güvenli çalışır” gibi genel ifadeler yerine hangi koşulun hangi sonucu doğurduğunu yazın. Eşzamanlı güncellemelerde ne olacağı, geçersiz filtrenin reddedilip reddedilmeyeceği ve tamamlanmamış işlemin nasıl gösterileceği anlaşılmalıdır. Aynı uç noktayı çağırabilen kullanıcıların farklı kayıtlara veya alanlara erişebileceğini de hesaba katın. Açıklamalar test senaryosu üretmeye elverişli olmalıdır. Davranış açıklamaları, kaynağın yaşam döngüsünü de tamamlamalıdır. Hangi durumdan hangi duruma geçilebildiği ve reddedilen bir işlemin mevcut veriyi etkileyip etkilemediği bilinmelidir. Böylece istemci ekipleri yalnızca doğru biçimde veri göndermeyi değil, işlemi doğru zamanda çağırmayı da öğrenir. Şema ve davranış kuralları birlikte değerlendirildiğinde arayüzün kullanım koşulları daha açık hâle gelir.
- ✓
Erişim kuralları
Güvenlik şemalarıyla birlikte işlem, kaynak ve alan düzeyindeki erişim gereksinimlerini açıklayın.
- ✓
Tekrarlanan istekler
Idempotency anahtarı kullanılıyorsa kapsamını, saklama politikasını ve farklı gövdeli tekrarların sonucunu belirtin.
- ✓
Sayfalama ve sınırlar
Sıralamayı, devam bilgisini ve sınır aşımlarında istemcinin karşılaşacağı sonucu tanımlayın.
Sözleşme değişikliklerini tüketici etkisiyle değerlendirin
OpenAPI belgesini uygulamayla birlikte sürüm kontrolünde tutun. İncelemede yalnızca teknik geçerliliğe değil, tüketiciye etkisine de bakın. Alan kaldırmak, tip değiştirmek veya isteğe zorunlu alan eklemek mevcut istemcileri etkileyebilir. Yanıta alan eklemek çoğu durumda daha düşük risklidir; yine de katı ayrıştırıcılar ve üretilmiş istemciler değerlendirilmelidir.
Yapısal olarak küçük bir değişiklik davranış açısından önemli olabilir. Durum alanına yeni bir değer eklemek veya liste sıralamasını değiştirmek mevcut beklentileri bozabilir. Otomatik sözleşme karşılaştırmasını tüketici senaryolarıyla tamamlayın. Kullanımdan kaldırılan işlemler için geçiş yolunu ve bilgilendirme sürecini açıklayın. OpenAPI belirtiminin sürümüyle API’nin dışarıya sunduğu sürümleme stratejisini birbirine karıştırmayın.
Geçiş planını tüketicilerin güncellenme biçimine göre oluşturun. Birlikte yayınlanan kurum içi uygulamalarla bağımsız iş ortakları aynı koordinasyon modeline sahip olmayabilir. Hangi uygulamanın hangi davranışa bağlı olduğunu gösteren bir tüketici envanteri bu değerlendirmeye yardımcı olur. Yayın notlarında yalnızca eklenen alanları değil, değişen beklentileri de anlatın; geriye uyumluluğu yalnızca dosya farkına bakarak değerlendirmeyin.
Uygulama süreci
Sözleşme testlerini geliştirme akışına ekleyin
Geçerli bir OpenAPI dosyası, çalışan servisin sözleşmeye uyduğunu tek başına göstermez. Dosya doğrulaması tanımın yapısını kontrol eder; sözleşme testleri uygulamanın beklenen istek ve yanıt kurallarına uygunluğunu değerlendirir. Tüketici beklentilerini doğrulayan testler ve iş kuralı testleri bu kontrolleri tamamlar. Test başarısı yalnızca test edilen kapsam için anlamlıdır. Sahte servisler istemci geliştirmesini başlatabilir; ancak gerçek uygulamanın davranışını kanıtlamaz. Örnek verilerle yapılan kontrolleri gerçek servisle çalışan senaryolarla tamamlayın. Doğrulama başarısız olduğunda uygulamanın mı, sözleşmenin mi, yoksa test beklentisinin mi hatalı olduğunu belirleyin. Sorunu yalnızca testi gevşeterek çözmek yerine ilgili ekiplerle karara bağlayın. Gerekli düzeltmeleri tanım, kod, örnekler ve tüketici beklentileriyle birlikte ele alın. Hata gövdeleri, isteğe bağlı alanlar ve içerik türleri özellikle kontrol edilmelidir. Böylece belgelenen davranışla çalışan sistem arasındaki farkın büyümesi önlenebilir. Başarısız kontrollerin kim tarafından değerlendirileceği ve hangi durumda yayının durdurulacağı da geliştirme akışında açık olmalıdır.
- 01
Tanımı doğrulayın
Sözdizimini, şema referanslarını ve ekip kurallarını kontrol edin.
- 02
Gerçek yanıtı karşılaştırın
Durum kodu, içerik türü, zorunlu alanlar ve veri tipleri açısından uyumu değerlendirin.
- 03
Olumsuz senaryoları çalıştırın
Eksik alan, geçersiz değer, yetkisiz erişim ve iş kuralı çakışmalarını test edin.
Kontrol listesi
Uygulamaya geçmeden önce ortak yorumu kontrol edin
İyi bir sözleşme, ekiplerin kritik konularda aynı yoruma ulaşabildiği belgedir. Bir istemci geliştiricisi yalnızca tanımı okuyarak doğru isteği oluşturabilmeli; servis ekibi de başarı, hata ve sınır durumlarını çıkarabilmelidir. Açıklama ihtiyacı sürekli sözlü görüşmelerle karşılanıyorsa bu bilgiyi sözleşmeye taşıyın. Hassas veriler yerine temsili örnekler kullanın. İncelemede farklı ekiplerin aynı senaryoyu nasıl yorumladığını karşılaştırın. Beklenen yanıtlar farklıysa ortak sözleşme henüz oluşmamıştır. Açık soruları, alınan kararları ve yeniden değerlendirilecek varsayımları kaydedin. Her ayrıntı hemen kesinleşmeyebilir; ancak belirsizliği kimin çözeceği belli olmalıdır. Güncel tutma sorumluluğunu yalnızca belge yazarına bırakmayın. Son kontrolün çıktısı yalnızca bir onay olmamalıdır. Uygulama ve test sorumluları, tüketicilere bilgi aktarımı ve sonraki inceleme adımları da netleşmelidir. Arayüzü değiştiren ekiplerin sözleşme güncellemesine katılması, belgenin geliştirmeden bağımsız ilerlemesini önler. Yeni ihtiyaçlar ortaya çıktığında kararların mevcut tanıma ve testlere nasıl işleneceği de bu süreçte belirlenmelidir.
- ✓
Örnekler tutarlı mı?
Örneklerin şemalarla, zorunlu alanlarla ve iş kurallarıyla çelişmediğini kontrol edin.
- ✓
Sahiplik açık mı?
İncelemeye katılacak ekipleri, test sorumluluğunu ve tüketicilere bilgi aktarımını belirleyin.
Keşfetmeye devam et
İlgili içerik ve hizmetler
Konuyu tamamlayan Bikare içeriklerine göz atın.
