Birçok yazılım ekibinde API'ler kodla birlikte doğar. Geliştirici bir uç nokta yazar, çalıştığını görür, ardından mobil ekibe "şu adrese şu alanlarla istek atın" diye haber verir. Dokümantasyon, eğer yazılırsa, en sona kalır ve kısa sürede gerçeği yansıtmaz hale gelir. Mobil ekip API hazır olana kadar bekler, iş ortağı entegrasyonları belirsiz e-posta yazışmalarıyla ilerler. Sözleşme öncelikli (contract-first) yaklaşım bu sırayı tersine çevirir: Önce API'nin ne yapacağı makine tarafından okunabilir bir sözleşmeyle tanımlanır, kod ve istemciler bu sözleşmeye göre geliştirilir.
Sözleşme nedir, neden önemlidir?
API sözleşmesi; uç noktaları, istek ve yanıt şemalarını, zorunlu ve isteğe bağlı alanları, veri tiplerini, hata yanıtlarını ve kimlik doğrulama yöntemini tanımlayan yapılandırılmış bir belgedir. Bu alandaki en yaygın standart OpenAPI belirtimidir. OpenAPI belgeleri YAML veya JSON biçiminde yazılır ve çok sayıda araç tarafından okunabilir.
Sözleşmenin değeri, tek bir doğruluk kaynağı olmasından gelir. Arka uç geliştiricisi, mobil geliştirici, test ekibi ve iş ortağı aynı belgeye bakar. "Bu alan zorunlu muydu?" sorusunun cevabı bir kişinin hafızasında değil, sözleşmededir.
Sözleşme öncelikli sürecin adımları
- İhtiyacı tanımlayın: Hangi kullanıcı senaryosunun desteklenmesi gerektiği yazılır. Örneğin "sahadaki temsilci, mobil uygulamadan DASK sorgusu başlatabilmeli ve sonuçları görebilmeli."
- Sözleşme taslağını yazın: Uç noktalar, şemalar ve hata durumları OpenAPI belgesinde tanımlanır.
- Gözden geçirin: Arka uç, mobil ve ürün ekipleri taslağı birlikte inceler. Bu aşamada yapılan bir değişiklik birkaç satırlık düzenlemedir; kod yazıldıktan sonra yapılan değişiklik ise saatler alır.
- Taklit sunucuyu başlatın: Sözleşmeden otomatik üretilen bir taklit (mock) sunucu, örnek yanıtlar döner. Mobil ekip gerçek API hazır olmadan geliştirmeye başlar.
- Uygulayın: Arka uç ekibi sözleşmeye uygun kodu yazar.
- Doğrulayın: Otomatik testler, gerçek API yanıtlarının sözleşmeye uyduğunu kontrol eder.
İyi bir sözleşmenin özellikleri
Branşa özgü şemalar
Trafik, kasko ve DASK sorguları farklı girdilere sahiptir. Tek bir genel teklif şeması içinde her alanı isteğe bağlı yapmak sözleşmeyi anlamsızlaştırır; çünkü hangi alanın hangi durumda zorunlu olduğu belirsizleşir. Her branş için ayrı istek şeması tanımlamak, hem istemci geliştiricisine net bir rehber sunar hem de otomatik doğrulamanın gerçekten işe yaramasını sağlar. Ortak alanlar, örneğin müşteri bilgileri, yeniden kullanılabilir bileşenler olarak tanımlanıp her branş şemasına referansla eklenebilir.
Açıklayıcı örnekler
Her şemaya gerçekçi ama kurgusal örnek değerler eklenmelidir. Örnekler, taklit sunucunun anlamlı yanıtlar dönmesini ve dokümantasyonun okunabilir olmasını sağlar. Örneklerde gerçek kişisel veri kesinlikle kullanılmamalıdır.
Hata yanıtlarının tanımı
Yalnızca başarılı yanıtlar değil, olası bütün hata yanıtları da sözleşmede yer almalıdır. Doğrulama hatası, yetki hatası, hız sınırı aşımı ve dış servis kaynaklı hatalar için ortak bir hata yapısı tanımlamak, istemcilerin hataları tutarlı biçimde işlemesini sağlar.
Açık tanımlar
Tarih alanlarının biçimi, tutar alanlarının birimi ve hangi kalemleri içerdiği, kimlik numarası gibi alanların doğrulama kuralları açıkça belirtilmelidir. Belirsiz bırakılan her tanım, ileride bir entegrasyon hatası olarak geri döner.
Sözleşmeden üretilebilecekler
OpenAPI sözleşmesi bir kez yazıldığında birçok yararlı çıktı otomatik olarak üretilebilir:
- Etkileşimli dokümantasyon: Geliştiricilerin tarayıcıdan uç noktaları inceleyip deneme istekleri gönderebildiği sayfalar.
- İstemci kütüphaneleri: Mobil uygulama veya iş ortakları için farklı dillerde tip güvenli istemci kodu.
- Sunucu iskeletleri: Arka uç tarafında yönlendirme ve doğrulama katmanları.
- Taklit sunucular: Geliştirme ve test ortamları için.
- İstek doğrulama ara katmanı: Gelen isteklerin şemaya uygunluğunu iş mantığına ulaşmadan kontrol eden bileşen.
Sözleşme testleri
Sözleşme ile gerçek davranış arasındaki uyum, otomatik testlerle sürekli doğrulanmalıdır. İki tür test özellikle değerlidir. Birincisi, API'nin her yanıtının sözleşmedeki şemaya uyduğunu doğrulayan testlerdir. İkincisi, her değişiklikte yeni sözleşmeyi önceki sürümle karşılaştırarak kırıcı değişiklikleri tespit eden testlerdir. Bu testler sürekli entegrasyon hattına eklendiğinde, sözleşmeyi bozan bir değişiklik yayına ulaşmadan yakalanır.
Tüketici odaklı sözleşme testleri ise bir adım daha ileri gider. Her istemci, API'den gerçekte hangi alanları kullandığını kendi test tanımında belirtir. Sağlayıcı taraf, bu tanımları kendi testlerinde çalıştırır. Böylece hangi değişikliğin hangi istemciyi etkileyeceği somut olarak görülür.
Sözleşmeyi yaşayan belge olarak tutmak
Sözleşme öncelikli yaklaşımın en büyük riski, sözleşmenin zamanla kenara itilmesi ve kodun ondan sapmasıdır. Bunu önlemek için sözleşme dosyası kodla aynı depoda tutulmalı, kod incelemelerinde sözleşme değişiklikleri de gözden geçirilmeli ve sözleşmeye uymayan yanıtlar test ortamında hata olarak işaretlenmelidir. Sözleşme bir kez yazılıp unutulan bir belge değil, ürünle birlikte evrilen bir tanımdır.
Kimler fayda sağlar?
Sözleşme öncelikli tasarımın faydası yalnızca geliştirici ekiplerle sınırlı değildir. Acentenin kendi web sitesini veya iç araçlarını platforma bağlamak isteyen teknik ekipler, net bir sözleşme sayesinde tahmine dayalı değil tanımlı bir arayüzle çalışır. Destek ekipleri, bir entegrasyon sorununda hatanın istemcide mi sağlayıcıda mı olduğunu sözleşmeye bakarak hızla ayırt edebilir.
Sözleşmede güvenlik tanımları
OpenAPI sözleşmesi yalnızca veri yapılarını değil, güvenlik gereksinimlerini de tanımlayabilir. Hangi uç noktanın hangi kimlik doğrulama yöntemini gerektirdiği, hangi kapsamların zorunlu olduğu ve hangi uç noktaların herkese açık olduğu sözleşmede açıkça belirtilmelidir. Bu tanımlar, otomatik güvenlik taramalarının yetkisiz erişime açık kalmış uç noktaları tespit etmesine de yardımcı olur.
InsureHub API sözleşmelerinin yaşam döngüsü
InsureHub, sigorta acentelerine yazılım sağlayan bir platform olarak web paneli, mobil sigorta uygulaması ve teklif motoru arasındaki arayüzlerin açık ve tutarlı tanımlanmasını, ürünün sürdürülebilirliğinin temeli olarak görür. Net sözleşmeler, sigorta acentesi yazılımı tarafındaki yeni özelliklerin farklı istemcilere aynı anda ve sorunsuz ulaşmasına yardımcı olur.