Git-Native Yöntemiyle API Tasarımı ve Geliştirme Nasıl Yapılır

Çoğu API ekibi sözleşmeyi sonradan akıllarına gelen bir detay olarak görür. Önce kodu yazar, sonra bir spesifikasyon oluşturur, ardından ikisinin birbirinden uzaklaşmasını izlerler. Git-yerel API tasarımı bu sırayı tersine çevirir. API sözleşmesini kaynak kodu olarak ele alır, Git'te versiyonlar ve her değişikliği uygulama mantığını incelediğiniz gibi incelersiniz.

Bu rehber tek bir araç hakkında değil, disiplin hakkındadır. Dallarda sözleşmeleri nasıl tasarlayacağınızı, çekme isteklerinde (pull request) nasıl inceleyeceğinizi ve kaydedilmiş bir spesifikasyonu nasıl taklitlere (mocks), testlere ve belgelere dönüştüreceğinizi öğreneceksiniz. Amaç, Git geçmişinizin API geçmişiniz olduğu bir iş akışı oluşturmaktır.

Eğer Önce Şartname (Spec-First) araçlarının neye benzediğini zaten biliyor ve ürün tanıtımını istiyorsanız, Git-yerel API iş akışı hakkındaki tamamlayıcı yazıyı okuyun. Bu makale uygulamaya odaklanmıştır.

API çalışması için "Git-yerel" ne anlama geliyor?

Git-yerel, API tanımınızın deponuzda düz metin dosyası olarak bulunması demektir. Tescilli bir bulut veritabanında değil. Bir satıcı girişinin arkasında değil. Ekibinizin zaten kullandığı aynı sürüm kontrolü tarafından izlenen, kodunuzun yanında duran bir .yaml veya .json dosyası.

Bunu bulut tabanlı araçlarla karşılaştırın. Birçok API tasarım platformu sözleşmeyi kendi arka uçlarında saklar. Web kullanıcı arayüzü (UI) aracılığıyla düzenleme yaparsınız ve ana sürüm onların sunucularında yaşar. Deponuz en iyi ihtimalle eski bir dışa aktarımı tutar. Satıcının veritabanı doğruluk kaynağı olduğunda, Git geçmişiniz API'nin nasıl geliştiği hakkında size hiçbir şey söylemez.

Git-yerel model bu ilişkiyi tersine çevirir. main dalındaki dosya sözleşmedir. GUI dahil diğer her şey, bu dosyanın bir görünümüdür. Bu tek değişiklik, API yüzeyiniz için geçmişi, sorumluluğu, geri almayı ve incelemeyi açığa çıkarır.

Bir Git-yerel kurulumunun üç özelliği vardır. Spesifikasyon depodaki bir metin dosyasıdır. Değişiklikler, dal oluşturma, taahhüt etme (commit) ve birleştirme (merge) gibi normal Git operasyonları aracılığıyla akar. Ve taklitlerden (mocks) belgelere kadar her alt akış yapısı, ayrı bir veritabanından ziyade kaydedilmiş dosyadan türetilir.

API'leri Git'te tasarlama ve geliştirme nedenleri

En değerli varlığınıza zaten Git ile güveniyorsunuz: kodunuza. API sözleşmeniz de aynı muameleyi hak ediyor.

Geçmiş ilk nedendir. Birisi "cursor sayfalama parametresini ne zaman ekledik?" diye sorduğunda, git log saniyeler içinde cevap verir. Onu tanıtan taahhüt bir mesaj, bir yazar ve bir tarih taşır. Ekran görüntüsü yok, değişiklik günlüğü arkeolojisi yok.

Sorumluluk (Blame) ikincisidir. Spesifikasyon dosyasında git blame komutunu çalıştırın ve her satırı kimin ne için değiştirdiğini tam olarak görün. Kafa karıştırıcı bir alan adı, tartışmasıyla birlikte eklendiği PR'ye kadar izlenebilir. Sorumluluk otomatikleşir.

Geri alma (Rollback) üçüncüdür. Kötü bir tasarım yayınlanır. Git ile, birleştirmeyi git revert edersiniz ve sözleşme önceki durumuna döner. Alt akıştaki kod üretimi, taklitler ve belgeler geri alınan dosyadan yeniden oluşturulur. Ayrı bir sistemde manuel temizlemeye gerek kalmaz.

İnceleme (Review) dördüncüdür ve ekiplerin yeterince kullanmadığı bir özelliktir. Bir çekme isteği (pull request), bir API tasarımını gerçek hale gelmeden önce tartışmak için doğal bir yerdir. İnceleyiciler, gerekli bir alan ekleyen bir + satırı hakkında yorum yapar. Konuşma değişikliğin yanında sonsuza dek yaşar.

Tek doğruluk kaynağı (Single source of truth) her şeyi bir araya bağlar. Sözleşme main dalında tek bir dosya olduğunda, hangi sürümün gerçek olduğu konusunda belirsizlik olmaz. Ön uç, arka uç, kalite güvence (QA) ve belgeler hepsi aynı YAML satırını okur. Bu, Git tabanlı bir API spesifikasyonu iş akışının temel vaadidir.

Git-yerel API tasarım döngüsü

Döngünün beş adımı vardır: sözleşmeyi tasarla, taahhüt et, bir PR aç, incele ve birleştir. Uygulama, birleştirmeden sonra gelir, tersi değil.

Sözleşmeyi yazarak başlayın. Diyelim ki bir kullanıcının faturalarını almak için bir uç nokta ekliyorsunuz. Bir dal (branch) oluşturur ve OpenAPI dosyasını düzenlersiniz.

# openapi.yaml (feat/invoices-list dalında eklenen alıntı)
paths:
 /users/{userId}/invoices:
 get:
 operationId: listUserInvoices
 summary: Bir kullanıcı için faturaları listele
 parameters:
 - name: userId
 in: path
 required: true
 schema: { type: string, format: uuid }
 - name: status
 in: query
 required: false
 schema:
 type: string
 enum: [draft, open, paid, void]
 responses:
 "200":
 description: Bir faturalar sayfası
 content:
 application/json:
 schema:
 $ref: "#/components/schemas/InvoiceList"
 "404":
 description: Kullanıcı bulunamadı

Bu değişikliği açık bir mesajla taahhüt edin: git commit -m "GET /users/{userId}/invoices sözleşmesini ekle". Taahhüt küçük ve odaklıdır. Tek bir tasarım kararını açıklar.

Şimdi bir çekme isteği (pull request) açın. Fark (diff), inceleyicilere tam olarak neyin yeni olduğunu gösterir: bir yol, bir işlem, iki parametre, iki yanıt. Takım arkadaşlarınız adlandırmayı, enum değerlerini ve kayıp bir kullanıcı için 404'ün doğru kod olup olmadığını tartışır. Tek bir satır işleyici kodu bile mevcut olmadan imleç tabanlı sayfalama için baskı yapabilirler.

PR onaylandığında, birleştirin. main dalındaki sözleşme artık faturalar uç noktasını içerir. Uygulama bir sonraki adımdır ve üzerinde anlaştığınız spesifikasyonla kısıtlanmıştır. Bu sıralama, insanların Önce Şartname (spec-first) API geliştirme derken kastettiği şeydir: anlaşma koddan önce gelir.

Bunun getirisi, tasarım tartışmalarının ucuza mal olmasıdır. İncelemede bir YAML alanını değiştirmek dakikalar sürer. Yayınlanmış, uygulanmış, belgelenmiş bir uç noktayı değiştirmek günler sürer.

API sözleşmeleri için dallanma stratejisi

Sözleşme değişikliklerini diğer değişiklikler gibi ele alın: mantıksal iş birimi başına bir dal. Uç nokta veya değişiklik başına bir dal, PR'leri küçük tutar ve farklılıkları okunabilir kılar.

Dalları niyet açık olacak şekilde adlandırın. Değişiklik sınıfını belirten bir ön ek kullanın. Bu, inceleyicilere ve CI'ya işi yönlendirmede yardımcı olur.

Önek anlam taşır. Bir break/api- dalı, inceleyicilere yavaşlamalarını ve her tüketiciyi kontrol etmelerini söyler. Bir chore/api- dalı anlamsal bir değişiklik olmadığını işaret eder, böylece inceleme hızlı ilerleyebilir.

Ayrıca bir dallanma modeli de seçersiniz. Ana dal tabanlı geliştirme (Trunk-based development) çoğu API ekibi için uygundur. Kısa ömürlü dallar günlük olarak main dalına birleştirilir ve spesifikasyon tek bir doğruluk çizgisine yakın kalır. Uzun süreli develop ve release dallarına sahip Gitflow, API değişikliklerini planlı sürümlere bölen ekipler için uygundur.

Çoğu API işi için, ana dal tabanlı (trunk-based) yaklaşımı tercih edin. Küçük, sık yapılan sözleşme değişiklikleri küçük, sık farklar üretir. Uzun ömürlü dallar, spesifikasyonun sapmasına izin verir ve iki dal aynı dosyayı yeniden yapılandırdığında YAML birleştirme çakışmaları hızla çirkinleşir.

Çekme isteklerinde API tasarımını inceleme

Bir spesifikasyon PR'ı bir tasarım incelemesidir, bir sözdizimi kontrolü değil. İnceleyiciler semantiklere bakar ve birkaç soru riskin çoğunu kapsar.

Bu mevcut tüketicileri bozuyor mu? Bir alanı kaldırmak, bir yolu yeniden adlandırmak veya bir türü sıkılaştırmak bozan değişikliklerdir. Bir inceleyici değişikliğin ekleyici mi yoksa bozan mı olduğunu kontrol eder ve bozan değişiklikler bir sürüm artışı veya bir kullanımdan kaldırma yolu gerektirir.

Adlandırma tutarlı mı? Her koleksiyon uç noktası çoğul isimler kullanıyorsa, yeni bir tekil yol göze çarpar. Başka yerlerde hatalar bir code alanı döndürüyorsa, yeni bir uç nokta da bunu yapmalıdır. İnceleyiciler, API'nin zaten oluşturduğu kalıpları uygular.

Fark dostu mu? Farkların küçük kalması için YAML'yi sabit tutun. Anahtarları tutarlı bir şekilde sıralayın. Yeni yolları tahmin edilebilir bir yere ekleyin. Bir inceleyici beş satırlık bir farkı saniyeler içinde okuyabilir, ancak yeniden sıralanmış bir dosya gerçek değişikliği gizleyen yüz satırlık bir fark üretir.

inceleyici dostu bozan değişiklik. - satırları tam olarak neyin kaybolduğunu işaret eder.

# İnceleyicinin PR'da gördüğü fark
 parameters:
 - name: status
 in: query
 schema:
 type: string
- enum: [draft, open, paid, void]
+ enum: [draft, open, paid, void, uncollectible]

Bu fark enum'a ekleyicidir, bu yüzden güvenlidir. Bunu void'i tamamen kaldıran bir - satırıyla karşılaştırın, bu değeri gönderen herhangi bir istemciyi bozacaktır. Fark, farkı bir bakışta görünür kılar.

İnceleyicileri, koda yorum yaptıkları gibi, spesifikasyon üzerinde satır içi yorum yapmaya teşvik edin. Tartışma satıra bağlı kalır ve birleştirilen geçmişte yaşamaya devam eder.

Tasarım aşamasından geliştirmeye

Sözleşme main dalına geçtiğinde, alt akıştaki her şey için kaynak haline gelir. Üretirsiniz, elle yazmazsınız.

İlk olarak kod üretimi (Codegen) gelir. openapi-generator gibi araçlar, kaydedilen dosyadan sunucu taslakları ve tip tanımlı istemciler üretir. İşleyicileriniz iş mantığını doldurur, ancak istek ve yanıt şekilleri yapıya göre sözleşmeyle eşleşir. Spesifikasyon ve kod, aktarım biçimi konusunda anlaşmazlık yaşayamaz.

Sıra taklitlere (Mocks) gelir. Bir taklit sunucusu spesifikasyonu okur ve her uç nokta için örnek yanıtlar döndürür. Ön uç geliştiricileri arka uç mevcut olmadan önce taklit sunucusuna karşı geliştirme yapar. Sözleşme birleştiği an başlarlar, haftalar sonra değil.

Testler takip eder. Sözleşme testleri, çalışan sunucunuzun spesifikasyonla eşleştiğini doğrular. Bir istek gönderin, yanıtı şemaya göre doğrulayın ve eğer farklılık gösteriyorsa yapıyı (build) başarısız kılın. Bu, spesifikasyon/kod sapmasına karşı bir güvenlik duvarıdır.

Belgeler de üretilir. Referans dokümantasyonu doğrudan OpenAPI dosyasından oluşturulur. Sözleşme değiştiğinde, belgeler de aynı taahhütte değişir. Unutulacak ayrı bir belge güncellemesi yoktur.

Prensip tutarlıdır. Her yapıt, tek bir kaydedilen dosyadan türetilir. Her birleştirmede yeniden oluşturun, böylece taklitleriniz, istemcileriniz, testleriniz ve belgeleriniz sözleşmeyle uyumlu kalır.

Ölçeklenebilir ekip kuralları

Ekip büyüdükçe Git-yerel bir iş akışının çökmesini engelleyen şey kurallardır. Bunları erken belirleyin ve yazılı hale getirin.

İlk olarak, bir mi yoksa çok mu spesifikasyon dosyası seçeceğinize karar verin. Tek bir openapi.yaml basit olsa da birkaç düzine uç noktadan sonra kullanışsız hale gelir. $ref referanslarıyla birden çok dosyaya bölmek, her dosyayı okunabilir tutar, ancak bir paketleme adımı maliyetine sahiptir. Yaygın bir desen, kaynak başına bir dosya olup, derleme zamanında tek bir spesifikasyonda birleştirilmesidir.

İkincisi, kasıtlı olarak versiyonlayın. Her anlamlı değişiklikte OpenAPI info.version değerini artırın ve anlamsal versiyonlamayı (semantic versioning) takip edin. Ekleyici değişiklikler küçük versiyonu (minor version) artırır. Bozan değişiklikler ana versiyonu (major version) artırır ve genellikle /v2/ gibi yeni bir yol öneki anlamına gelir.

Üçüncüsü, bir değişiklik günlüğü (changelog) tutun. Spesifikasyonun yanında bulunan bir CHANGELOG.md, neyin ve neden değiştiğini insan terimleriyle kaydeder. Git geçmişi hassastır ancak laf kalabalığı içerir; değişiklik günlüğü, tüketicilerinizin gerçekten taradığı okunabilir özettir.

Dördüncüsü, spesifikasyonu CODEOWNERS ile koruyun. Sözleşme dosyasındaki herhangi bir değişikliği API sorumlularının onaylamasını zorunlu kılın. Bu, iyi niyetli katkıda bulunanların tutarsız tasarımlar yayınlamasını engeller.

# .github/CODEOWNERS
/api/openapi.yaml @api-sorumluları
/api/paths/ @api-sorumluları

Beşincisi, CI'da kod analizi (lint) yapın. Bir kod analizci, incelemeden önce stil ve tutarlılık sorunlarını yakalar. Her PR'da çalıştırın, böylece insanlar biçimlendirmeyi değil, tasarımı inceler.

# .github/workflows/api-lint.yml
name: API Kod Analizi
on:
 pull_request:
 paths: ["api/"]
jobs:
 spectral:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 - name: Spectral'ı Çalıştır
 run: npx @stoplight/spectral-cli lint api/openapi.yaml --fail-severity warn

CI kod analizi ve CODEOWNERS ile, her sözleşme değişikliği otomatik kontrollerden ve bir insan sorumlunun denetiminden geçer. Bu kombinasyon üç mühendisten üç yüze kadar ölçeklenebilir.

Yaygın tuzaklar ve bunlardan nasıl kaçınılacağı

Git-yerel API tasarımının öngörülebilir hata modları vardır. Bunları bilmek, etrafından dolaşarak tasarım yapmanızı sağlar.

Spesifikasyon/kod sapması en kötüsüdür. Sözleşme bir şey söyler; çalışan sunucu başka bir şey yapar. Bunu, çalışan sunucunuzdaki canlı yanıtları kaydedilen spesifikasyona karşı doğrulayan CI'daki sözleşme testleriyle önleyin. Eğer sapma olursa, yapı (build) başarısız olur. Sapma, bir üretim sürprizi değil, bozuk bir pipeline haline gelir.

Devasa PR'lar bir sonraki tuzaktır. Yirmi uç nokta ekleyen tek bir dal, incelenemez bir fark (diff) üretir. İnceleyiciler hızla göz gezdirir, onaylar ve sorunları kaçırır. İşi, PR başına bir uç nokta veya bir değişikliğe bölün. Küçük farklar gerçek bir inceleme alır.

Elle yazılmış yapıtlar sessiz tutarsızlığa neden olur. Birisi bir istemciyi oluşturmak yerine elle yazdığında, istemci spesifikasyondan sapar. İstemcileri, taslakları ve belgeleri her seferinde kaydedilen dosyadan oluşturun. Elle yazılmış API yapıtlarını bir "kötü kokuyu" (smell) göstergesi olarak ele alın.

YAML birleştirme çakışmaları, uzun ömürlü dallarda ekipleri çıldırtır. İki dal aynı dosyayı yeniden yapılandırır ve Git bunları uzlaştıramaz. Bunu kısa ömürlü dallar, sabit bir anahtar sırası ve değişikliklerin farklı dosyalara dokunması için bölünmüş dosya düzeniyle önleyin. Ana dal tabanlı geliştirme ve küçük PR'lar çoğu çakışmayı başlamadan önce ortadan kaldırır.

Dördünün ortak deseni aynıdır. Değişiklikleri küçük tutun, yapıtları spesifikasyondan türetin ve CI'ın sözleşmeyi uygulamasını sağlayın. Disiplin kahramanlığı yener.

Apidog nerede devreye giriyor?

Git-yerel bir iş akışını bir metin düzenleyici ve bir CLI ile yürütebilirsiniz. Birçok ekip, doğruluk kaynağı olarak Git'ten vazgeçmeden tasarım için bir GUI ister. Apidog'un Önce Şartname (Spec-First) Modu işte bu boşluğu doldurur.

Önce Şartname Modu, OpenAPI dosyasını Git deponuzda tutar ve iki yönlü senkronizasyona sahiptir. Sözleşmeyi Apidog'un görsel tasarımcısında veya düzenleyicinizde düzenlersiniz ve her ikisi de deponuzdaki dosyayla tutarlı kalır. Git'teki dosya ana (canonical) kalır, bu nedenle dallar, PR'lar ve geçmiş tam olarak burada açıklandığı gibi çalışır. Bulut bağımlılığı olmadan GUI elde edersiniz. Kurulum detayları için Önce Şartname Modu belgelerine bakın.

Mesele araç değildir. Mesele, aynı anda hem görsel bir tasarım yüzeyine hem de Git-yerel bir disipline sahip olabilmenizdir. Depo, tek doğruluk kaynağı olarak kalır ve Apidog, ona bakan bir görünüm haline gelir.

Sıkça Sorulan Sorular

Git-yerel API tasarımı sadece OpenAPI için midir?

Hayır. Disiplin, metin tabanlı herhangi bir sözleşme biçimi için geçerlidir. OpenAPI en yaygın olanıdır, ancak aynı iş akışı AsyncAPI, gRPC .proto dosyaları veya GraphQL SDL için de çalışır. Sözleşme farklılıklarını gösterebileceğiniz, dallara ayırabileceğiniz ve inceleyebileceğiniz bir metin dosyası olduğu sürece, Git-yereldir.

Git-yerel bir iş akışında bozan değişiklikleri nasıl ele alırım?

Bozan değişiklikleri görünür ve kasıtlı hale getirin. Bir break/api- dal öneki kullanın, ana sürümü (major version) artırın ve CODEOWNERS aracılığıyla sorumlunun onayını isteyin. Mümkünse, eski yolun yanına yeni şekli ekleyin ve eski yolu belirli bir zaman çizelgesinde kullanımdan kaldırın. PR farkı (diff) ve sürüm artışı birlikte, her tüketiciye bozan değişikliği işaret eder.

API spesifikasyonu kodla aynı depoda mı yaşamalı?

Genellikle evet, tek bir ekip her ikisine de sahip olduğunda. Spesifikasyon ve uygulamanın aynı yerde bulunması, tek bir PR'nin sözleşmeyi ve işleyiciyi birlikte değiştirebileceği ve sözleşme testlerinin tek bir pipeline'da çalışabileceği anlamına gelir. Spesifikasyonu ayrı bir depoya yalnızca birçok ekip bir ortak API'yi tükettiğinde ve bağımsız versiyonlamaya ihtiyaç duyduğunda koyun.

Spesifikasyon ve kodun birbirinden uzaklaşmasını nasıl önlerim?

CI'ya sözleşme testleri ekleyin. Çalışan sunucunuza gerçek istekler gönderir ve her yanıtı kaydedilen spesifikasyona karşı doğrularlar. Bir sapma, yapıyı (build) başarısız kılar. Spesifikasyondan taslakları ve istemcileri oluşturmakla birleştiğinde, sözleşme testleri sapmayı bir üretim hatası yerine bir pipeline hatası haline getirir.

Sonuç

Git-yerel API tasarımı bir ürün değil, bir disiplindir. Sözleşmeyi kaynak kodu olarak ele alır, dallarda geliştirir, çekme isteklerinde inceler ve her alt akış yapıtını kaydedilmiş dosyadan üretirsiniz. Geçmiş, sorumluluk, geri alma ve inceleme ücretsiz gelir çünkü Git bunları size zaten sunar.

Küçük başlayın. Spesifikasyonunuzu depoya taşıyın, bir kod analizi (lint) adımı ekleyin ve sözleşme değişiklikleri için inceleme isteyin. Oradan kod üretimi (codegen), taklitler (mocks) ve sözleşme testleri ile inşa edin. İş akışı katlanır: her kural bir sonrakini kolaylaştırır ve Git geçmişiniz API'nizin nasıl büyüdüğünün eksiksiz bir kaydı haline gelir.

Eğer spesifikasyonu Git'te tutan görsel bir tasarım yüzeyi istiyorsanız, Apidog'daki Önce Şartname (Spec-First) Modunu deneyin ve iki yönlü senkronizasyonun yukarıdaki iş akışına nasıl uyduğunu görün.