Düzeltmem için çağrıldığım her entegrasyon kâbusu aynı şekilde başlar: biri önce ürünü inşa etmiş, API'yi sonradan düşünmüştür. Veritabanı şeması uç noktalara sızmıştır. Mobil ekip, üç CEO'dan daha uzun ömürlü olan "geçici" bir JSON yığını almıştır. Ve bir iş ortağı nihayet programatik erişim istediğinde, dürüst yanıt şu olmuştur: "Bize bir çeyrek verin."
API öncelikli tasarım bu sıralamayı tersine çevirir. Arayüzü, ürünün ilk teslimatı olarak ele alırsınız — tek bir satır iş mantığı var olmadan önce tasarlanmış, gözden geçirilmiş ve üzerinde mutabık kalınmış. Kulağa bir süreç yükü gibi geliyor. Uygulamada ise, çoğu sistemi üçüncü yılına gelmeden sessizce boğan entegrasyon borcuna karşı satın alabileceğiniz en ucuz sigortadır.
"API öncelikli" aslında ne demektir (ve ne demek değildir)
Bu "REST uç noktalarımız var" demek değildir. Bunlara neredeyse herkeste vardır. API öncelikli, sözleşmenin koddan önce gelmesi demektir. OpenAPI veya GraphQL şemasını yazarsınız, onu dolaşıma sokarsınız, tüketicilerin — mobil, web, iş ortakları, kendi gelecekteki servisleriniz — değişiklikler hâlâ bedavayken bunun üzerine tartışmasına izin verirsiniz. Ancak ondan sonra herhangi biri geliştirmeye başlar.
Bu ayrım, geri bildirimin ne zaman geldiği yüzünden önemlidir. Kod öncelikli bir ekipte, API, ORM'in ne ürettiyse onun tesadüfi bir yan ürünüdür. Tasarımın yanlış olduğunu, bir istemci onu kullanmaya çalıştığı gün keşfedersiniz — ki bu, öğrenmek için mümkün olan en pahalı andır. API öncelikli yaklaşım, bu keşfi öne çeker; burada bir yeniden adlandırma, bir kullanımdan kaldırma döngüsü yerine bir pull-request yorumuna mal olur.
Sözleşme, ürünün kendisidir. Uygulama (implementation) ise yalnızca onu şu an için yerine getirme biçiminizdir.
Neden karşılığını verir — ve para aslında nerede
Bariz kazanç paralelliktir. Sözleşme dondurulduğunda, ön yüz, arka yüz ve iş ortağı ekipleriniz birbirinin arkasında sıraya girmek yerine aynı anda bir sahte (mock) sunucuya karşı çalışır. Danışmanlık çalışmalarımda, yalnızca bu bile, iki aylık ardışık bir geliştirmeyi rutin olarak beş ya da altı paralel haftaya sıkıştırır.
Daha az bariz kazançlar daha güçlü biçimde bileşik faiz gibi büyür:
- Taklit edilebilirlik (mockability). Şema güdümlü bir sahte servis (Prism, WireMock, MSW), test (QA) ve tasarım ekiplerinin, arka yüz var olmadan önce, gerçekçi yanıtlara karşı daha ilk günden başlamasını sağlar.
- Her şeyin üretilmesi. Tek bir OpenAPI dosyası; istemci SDK'lerini, sunucu iskeletlerini (stub), tipli modelleri ve dokümantasyonu üretir. Dokümanlar gerçeklikten uzaklaşamaz, çünkü aynı kaynaktan inşa edilirler.
- Sözleşme testleri. Pact gibi araçlar, kırıcı bir değişikliği gece 2'de bir iş ortağının olay kanalında değil, CI'da yakalar.
- Seçeneklilik (optionality). Servisi Go ile yeniden yazın, üçe bölün, bir kuyruğun arkasına taşıyın — tüketiciler bunu asla fark etmez, çünkü onlar en baştan yalnızca sözleşmeye bağlıydı.
Pazartesi bunu gerçekte nasıl yapmalı
Bir platform ekibine ya da bir yıllık kaynağa (runway) ihtiyacınız yok. Belirli bir sırayla disipline ihtiyacınız var.
1. Sözleşmeyi açıkça tasarlayın
Belirtimi (spec) depoda gözden geçirilebilir bir dosya olarak yazın — REST için OpenAPI 3.1, GraphQL için bir SDL. Ona karşı açılan pull request'leri mimari kararlar gibi ele alın, çünkü öyleler. Yalnızca servisin sahibi olan ekibi değil, gerçek tüketicileri de gözden geçirmeye dâhil edin.
2. Veritabanı satırlarını değil, kaynakları modelleyin
API'niz bir SQL dökümü değil, bir alan dilidir. Şeyleri işin konuştuğu gibi adlandırın: faturalar, sevkiyatlar, abonelikler — tbl_inv_2 değil. Bir uç nokta ancak biri tablo düzeninizi açıkladıktan sonra anlam kazanıyorsa, onu yeniden tasarlayın.
3. Bilinçli olarak sürümleyin ve geliştirin
Uyumluluk kurallarınızı lansmandan önce kararlaştırın: ekleyici değişiklikler bedavadır, kaldırmalar ve yeniden adlandırmalar kırıcıdır ve kırıcı değişiklikler, gerçek bir kullanımdan kaldırma penceresiyle yeni bir sürüm alır. Bunu yazın. Bunu atlayan ekipler, canlı ortamda v1, v1_new ve v1_final ile son bulur.
4. Koruma bariyerlerini otomatikleştirin
Belirtimi denetleyin (Spectral), kırıcı değişiklikleri işaretlemek için son sürümle karşılaştırın ve CI'da ondan istemciler üretin. Sözleşmeyi makine uyguladığında, "dikkatli olacağız" tek savunmanız olmaktan çıkar.
Dürüst ödünleşmeler
API öncelikli yaklaşım bedava değildir ve bunun aksini varsaymak, onun terk edilmesine yol açar. Boş bir şemaya bakarken ve demo cuma günüyken, önden tasarım yavaş hissettirir. Gerçekten tek kullanımlık, atılacak bir prototip için bunu atlayın — tören, getirisinden ağır basar. Ama o arayüze birden fazla ekip ya da bir dış taraf bağımlı olduğu an, matematik sert biçimde tersine döner. Kötü bir sözleşmenin bedelini siz ödemezsiniz; onu ona karşı entegre eden herkes, defalarca, yıllarca öder.
Diğer tuzak, belirtimi sonradan yazdığınız bir dokümantasyon olarak görmektir. Çalışan koddan ürettiğiniz bir sözleşme API öncelikli değildir — daha iyi PDF'lere sahip, kod öncelikli bir yaklaşımdır. İşin bütün özü, tasarımın, uygulama onu yönlendirebilmeden önce gerçekleşmesidir.
Nereden başlamalı
Bir sonraki yeni servisinizi seçin — bir yeniden yazım değil, sıfırdan (greenfield) bir servis. Herhangi biri düzenleyicisini açmadan önce, OpenAPI dosyasını yazın, ondan bir sahte servis ayağa kaldırın ve ön yüz ile bir alt tüketicinin bir hafta boyunca o sahte servise karşı geliştirme yapmasını sağlayın. Farkı daha ilk koşuda (sprint) hissedeceksiniz: daha az "dur, bu alan ne anlama geliyor" mesajı, engellenmiş ekip yok ve gelişigüzel dışarı salınmış gibi değil, tasarlanmış gibi okunan bir API.
Bir dahaki sefere "uç noktaları bağla, belgelemesini sonra yap" cazibesine kapıldığınızda, bu kararın bedelini kimin ödeyeceğini — ve bunun gerçekten siz olup olmadığınızı — kendinize sorun.