API-First Yaklaşımı: Önce Sözleşme, Sonra Kod

API-first nedir?

API-first (API öncelikli), bir yazılım ürününü geliştirirken API'yi sonradan eklenen bir bileşen değil, ürünün birincil arayüzü olarak ele alan yaklaşımdır. Kod yazmaya başlamadan önce API'nin neyi sunacağı, hangi isteklere nasıl yanıt vereceği ve hangi hata durumlarını döndüreceği bir sözleşme (contract) olarak tasarlanır ve ilgili herkesle gözden geçirilir.

Geleneksel yöntemde ekipler önce uygulamayı kurar, API'yi ihtiyaç doğdukça ortaya çıkarır. Sonuç genellikle tutarsız adlandırma, belgelenmemiş davranışlar ve sonradan eklenen yamalar olur. API-first bu sırayı tersine çevirir: sözleşme ilk ürün çıktısıdır, uygulama onu hayata geçiren işlemdir.

Bu yaklaşım web, mobil, iş ortakları ve dahili servisler gibi birden fazla tüketicinin aynı arayüzü kullandığı durumlarda özellikle değerlidir.

Nasıl işler?

Süreç genellikle şu akışla ilerler: • İhtiyaç netleştirilir: API'yi kimler, hangi amaçla tüketecek? • Sözleşme tasarlanır: uç noktalar, kaynaklar, istek ve yanıt şemaları, hata biçimleri, kimlik doğrulama OpenAPI gibi makine tarafından okunabilir bir tanım diliyle yazılır. • Tüketicilerle gözden geçirilir: ön yüz, mobil ve iş ortağı ekipleri sözleşmeyi uygulama yazılmadan inceler, itirazlar erken gelir. • Mock sunucu üretilir: tanımdan sahte yanıt veren bir sunucu ayağa kalkar. • Paralel geliştirme yapılır: arka uç ekibi uygulamayı yazarken ön yüz ekibi mock sunucuya karşı çalışır. • Sözleşme testleri yazılır: gerçek uygulamanın tanıma uyup uymadığı otomatik doğrulanır.

Sözleşme tek gerçek kaynak (single source of truth) olur. Belgeler, istemci kodu ve testler bu tanımdan türetilir.

Küçük bir örnek

Örneğin bir sipariş yönetimi ürününde web arayüzü, mobil uygulama ve bir kargo iş ortağı entegrasyonu aynı API'yi kullanacak. Kod-first yaklaşımda arka uç ekibi önce uygulamayı bitirir; web ve mobil ekipler bekler, sonra alanların adlarının ve hata biçimlerinin birbirini tutmadığını görür.

API-first yaklaşımda önce sipariş kaynağı, durum geçişleri, sayfalama ve hata yanıtları tanımlanır, tüm tüketiciler bunu inceler. Mock sunucu hemen yayına alınır. Ön yüz ekipleri aynı gün gerçeğe çok yakın veriyle çalışmaya başlar, arka uç paralelde uygulamayı yazar. Entegrasyon sürprizleri azalır.

İş ortağı için de ayrı bir belge hazırlamak gerekmez: sözleşmeden üretilen etkileşimli belge hazırdır.

API-first, code-first ve tasarım yönetişimi

Code-first yaklaşımda API tanımı koddan türetilir; hızlı başlanır ama tasarım kararları kod içinde dağılır ve tüketici bakış açısı zayıf kalabilir. API-first ise (contract-first olarak da anılır) sözleşmeyi koddan önce ve koddan bağımsız tutar. Küçük, tek tüketicili bir proje için code-first yeterli olabilir; çoklu tüketicili ürünlerde API-first düzen sağlar.

API-first'ün kritik bir parçası yönetişimdir. Adlandırma kuralları, hata biçimi, sayfalama, sürümleme ve kimlik doğrulama için ortak tasarım standartları belirlenir. Otomatik kural denetimleri (linting) sözleşmelerin bu standartlara uyup uymadığını gözden geçirme aşamasından önce yakalar.

Bu yaklaşım REST ile sınırlı değildir; GraphQL ya da gRPC gibi başka arayüz biçimlerinde de sözleşme-önce düşüncesi geçerlidir.

Faydaları ve zorlukları

Faydalar: ekipler paralel çalıştığı için teslim süresi kısalır; tutarlı bir geliştirici deneyimi oluşur; belgeler ve istemci kodu otomatik üretilebilir; yanlış anlaşılmalar erken görünür olur; ürün ilerledikçe geriye uyumluluğu yönetmek kolaylaşır.

Zorluklar: tasarım aşaması başta zaman ister ve disiplin gerektirir. Sözleşme gerçekle ayrışırsa avantaj kaybolur, bu yüzden sözleşme testleri şarttır. Sözleşmenin değişikliği sürümleme ve duyuru süreçleri gerektirir. Aşırı erken tasarım da risklidir: belirsiz bir ürün için tüm API'yi baştan dondurmak yerine küçük bölümler halinde ilerlemek daha sağlıklıdır.

İyi uygulamalar: tüketicileri tasarıma dahil etmek, sözleşmeyi sürüm kontrolünde tutmak, her değişikliği gözden geçirmek ve mock ile gerçek uygulamayı aynı tanıma karşı otomatik doğrulamak.

Nerede ve kimler için kullanılır?

API-first, birden çok istemcisi olan ürünlerde, mikroservis mimarilerinde, platform ve entegrasyon ürünlerinde, iş ortağı ekosistemlerinde ve ürününün kendisi API olan şirketlerde yaygındır. Ürün yöneticileri, yazılım mimarları, arka uç ve ön yüz geliştiricileri, test mühendisleri ve teknik yazarlar sürecin doğal paydaşlarıdır.

Sözlükteki komşu kavramlarla ilişkisi şöyledir: REST API bir arayüz tasarım tarzıdır, API gateway bu arayüzlerin önündeki yönetim katmanıdır, API-first ise bunların nasıl ve hangi sırayla tasarlanacağına dair bir yaklaşımdır.

Bu yaklaşımı uygulamalı öğrenmek isteyenler için Mindset'in API-First Ürün Geliştirme Süreci programı; sözleşme öncelikli tasarım, mock sunucu ve paralel geliştirme ile tasarım standartları ve yönetişim modüllerini içerir.