API sözleşmesi yazarken OpenAPI belgesi nasıl kurgulanır

OpenAPI ve Swagger arasındaki ilişki nedir?

OpenAPI, HTTP tabanlı API'leri makinenin ve insanın okuyabileceği tek bir dosyada tanımlamaya yarayan bir belirtimdir. Swagger ise bu belirtimin ilk çıktığı dönemdeki adıdır ve bugün çoğunlukla belirtimin etrafındaki araç ailesini (arayüz, düzenleyici, kod üreticiler) anlatmak için kullanılır. Günlük konuşmada adlar sık sık birbirinin yerine geçer; teknik olarak belirtim OpenAPI'dir, Swagger ise ona bağlı araçların markasıdır.

Bir OpenAPI dosyası; API'nin hangi uç noktaları sunduğunu, her uç noktanın hangi parametreleri aldığını, hangi gövdeyle çağrıldığını, hangi yanıtları döndürdüğünü ve hangi güvenlik yöntemini beklediğini tanımlar. Dosya YAML ya da JSON biçimindedir. Değeri, tek bir doğruluk kaynağı olmasıdır: dokümantasyon, istemci kodu, test ve sahte sunucu aynı dosyadan beslenebilir.

Sözleşme öncelikli yaklaşım neden tercih edilir?

Geleneksel akışta önce kod yazılır, sözleşme sonradan koddan çıkarılır. Sözleşme öncelikli yaklaşımda sıra tersine döner: önce API'nin sözleşmesi tasarlanır ve ilgili taraflarla gözden geçirilir, sonra uygulama yazılır. Bunun pratik faydaları vardır.

Önce, ön yüz ekibi ve entegrasyon yapacak ortaklar arka yüz bitmeden çalışmaya başlayabilir, çünkü arayüzün şekli artık bellidir. Ayrıca tasarım hataları (tutarsız adlandırma, eksik hata durumu, yanlış kaynak modeli) koda dökülmeden önce ucuza yakalanır. Sözleşme bir sözleşme olarak da işler: kod ve belge birbirinden sapmaya başladığında bunu bir araç fark edebilir. Karşılığında disiplin gerekir; sözleşme dosyası gerçekten ekibin ortak işi olmalı, kod ile birlikte sürüm kontrolünde yaşamalıdır.

Bir OpenAPI dosyası nasıl yapılandırılır?

Dosyanın üst düzey bölümleri şöyle düşünülebilir:

• Bilgi: API'nin adı, açıklaması ve sürümü.
• Sunucular: API'nin hangi adreslerde yayınlandığı (örneğin test ve canlı ortam).
• Yollar: Her yol ve HTTP yöntemi için işlem tanımı; parametreler, istek gövdesi, yanıtlar.
• Bileşenler: Birden çok yerde yeniden kullanılan şemalar, parametreler, yanıtlar ve güvenlik şemaları.
• Güvenlik: Hangi işlemlerin hangi kimlik doğrulama yöntemini gerektirdiği.
• Etiketler: İşlemleri belgede mantıksal gruplara ayırmak için.

İyi bir başlangıç, kaynağı düşünmektir: önce "müşteri", "sipariş" gibi kaynakları ve aralarındaki ilişkiyi belirleyin, sonra her kaynak için hangi işlemlerin gerektiğini yazın. Her işleme anlamlı bir tanımlayıcı ve kısa açıklama verin; bu tanımlayıcılar ileride istemci kodu üretirken fonksiyon adlarına dönüşebilir.

Şema modelleme ve bileşen tasarımı

Tasarımın en çok emek isteyen kısmı şemalardır. Her veri yapısını bileşenler altında bir kez tanımlayıp işlemlerden bu tanıma başvurmak, tekrarı ve tutarsızlığı önler. Örneğin bir adres yapısı hem müşteri hem sipariş yanıtında geçiyorsa tek bir şema olarak tanımlanır.

Şema yazarken şunlara dikkat edin: zorunlu alanları açıkça işaretleyin; alanın türünü ve gerekiyorsa biçimini (tarih, e-posta, tanımlayıcı) belirtin; kabul edilen değerler sınırlıysa bunu numaralandırma ile ifade edin; boş olabilen alanları açıkça belirtin. Kalıtım benzeri durumlar için belirtimin birleştirme ve seçim yapılarını kullanabilirsiniz, ancak bunları ölçülü kullanmak gerekir, çünkü aşırı karmaşık şemalar hem okunmayı hem kod üretimini zorlaştırır. Alan adlarında tek bir yazım düzeni (örneğin hep aynı harf kuralı) seçip tüm dosyada koruyun.

Hata sözleşmesi ve güvenlik tanımları

Başarılı yanıtı tanımlamak kolaydır; asıl olgunluk, hataları tanımlamakta görünür. İyi bir sözleşme, istemcinin neye hazırlanması gerektiğini söyler: geçersiz istek, kimlik doğrulama başarısızlığı, yetki yokluğu, bulunamayan kaynak, çakışma ve sunucu hatası gibi durumlar için yanıt biçimleri tanımlanır. Tüm hatalar için ortak bir hata şeması kullanmak, istemci tarafında tek bir hata işleme mantığı yazmayı mümkün kılar.

Güvenlik tarafında belirtim, kimlik doğrulama yöntemlerini bileşenler altında tanımlamanıza ve işlemlerde hangisinin gerektiğini belirtmenize izin verir. Anahtar tabanlı, taşıyıcı belirteç ve yetkilendirme akışı tabanlı yöntemler anlatılabilir. Burada amaç, güvenliği sağlamak değil, istemciye nasıl kimlik doğrulayacağını açık ve makine tarafından okunur biçimde söylemektir; gerçek koruma uygulamada sağlanır.

Taklit sunucu, kod üretimi ve sözleşme testi

Sözleşme yazıldıktan sonra ondan somut değer üretmeye başlarsınız. Taklit (mock) sunucu araçları, dosyadaki örnek yanıtlardan sahte bir API ayağa kaldırır; ön yüz ekibi gerçek arka yüzü beklemeden entegrasyon geliştirebilir. Kod üreticiler ise sözleşmeden istemci kütüphaneleri ya da sunucu iskeleti çıkarabilir; bu, elle yazılan tekrarlayan kodu ve eşleşme hatalarını azaltır.

Sözleşme testi, kodun gerçekten sözleşmeye uyup uymadığını denetler. Bir örnek akış: sürekli entegrasyon hattında önce sözleşme dosyası bir doğrulayıcıdan geçer, ardından çalışan uygulamaya karşı otomatik istekler atılır ve dönen yanıtlar şemalara göre denetlenir. Uyuşmazlık varsa derleme başarısız olur. Ayrıca bir önceki sözleşme sürümü ile yeni sürüm karşılaştırılarak geriye dönük uyumsuz değişiklikler (örneğin bir alanın kaldırılması) yayın öncesi yakalanabilir.

Sık yapılan hatalar

• Sözleşmeyi bir kez yazıp bırakmak: Kod değiştikçe sözleşme güncellenmezse değer kaybeder. Sözleşme değişikliğini çekme isteğinin zorunlu parçası yapın.
• Her şeyi satır içinde tanımlamak: Bileşen kullanmadan aynı şemayı defalarca kopyalamak bakımı imkânsız hâle getirir.
• Hata yanıtlarını atlamak: Yalnızca başarılı durumu yazılmış bir sözleşme istemciyi yarı yolda bırakır.
• Gerçekçi olmayan örnekler: "string" gibi anlamsız örnek değerler hem belgeyi hem taklit sunucuyu işe yaramaz kılar. Anlamlı örnek değerler yazın.
• Tutarsız adlandırma: Aynı kavramın farklı uç noktalarda farklı adlarla geçmesi.
• Sürümleme düşünmemek: Geriye dönük uyumsuz değişikliklerin nasıl yönetileceği baştan kararlaştırılmalıdır.

Öğrenme yolunda mantıklı sıra şöyledir: önce küçük bir API'nin sözleşmesini elle yazın, ardından bileşenlere ayırmayı öğrenin, sonra taklit sunucu ve kod üretimini deneyin, en son sözleşme testini hattınıza ekleyin.

Bu beceriyi Mindset programlarında nerede çalışırsınız?

OpenAPI ile Sözleşme Öncelikli API Tasarımı programı, bu sayfadaki akışla aynı başlıkları taşıyan modüllerden oluşur: Sözleşme Öncelikli Yaklaşım ve OpenAPI Yapısı, Şema Modelleme ve Bileşen Tasarımı, Hata Sözleşmesi ve Güvenlik Tanımları, Taklit Sunucu ve Kod Üretimi, Şema Yönetişimi ve Kalite Denetimi ile Sözleşme Testleri ve CI Entegrasyonu.