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

Çoğu API ekibi sözleşmeyi en sona bırakır: önce kod yazılır, sonra spesifikasyon çıkarılır, ardından kod ile sözleşme yavaşça ayrışır. Git-yerel API tasarımı bu sırayı tersine çevirir: API sözleşmesini kaynak kodu gibi ele alır, Git’te versiyonlar, dallarda geliştirir ve her değişikliği pull request üzerinden incelersiniz.

Apidog'u bugün deneyin

Bu rehber tek bir araçtan çok uygulanabilir bir iş akışına odaklanır. API sözleşmelerini dallarda nasıl tasarlayacağınızı, pull request’lerde nasıl inceleyeceğinizi ve merge edilen bir spesifikasyonu mock, test, codegen ve dokümantasyona nasıl bağlayacağınızı adım adım göreceksiniz. Hedef basit: Git geçmişiniz aynı zamanda API geçmişiniz olsun.

Spec-first araçlarının nasıl göründüğünü biliyor ve ürün odaklı bir bakış istiyorsanız, Git-yerel API iş akışı hakkındaki tamamlayıcı yazıyı okuyabilirsiniz. Bu makale uygulamaya odaklanır.

API çalışması için “Git-yerel” ne anlama gelir?

Git-yerel, API tanımınızın deponuzda düz metin dosyası olarak yaşaması demektir. Yani doğruluk kaynağı bir satıcı veritabanı, kapalı bir bulut projesi veya manuel dışa aktarım değil; ekibinizin zaten kullandığı Git deposundaki bir .yaml veya .json dosyasıdır.

Bulut tabanlı birçok API tasarım aracında sözleşme aracın kendi arka ucunda saklanır. Web UI’dan düzenleme yapılır, ana sürüm orada yaşar, repo ise çoğu zaman eski bir export dosyasını tutar. Bu durumda Git geçmişiniz API’nin nasıl değiştiğini tam olarak göstermez.

Git-yerel modelde ilişki tersine döner:

• main dalındaki OpenAPI dosyası sözleşmedir.
• GUI, CLI, mock sunucusu ve dokümantasyon bu dosyadan türetilir.
• API geçmişi, git log, git blame, pull request ve revert mekanizmalarıyla izlenir.

Pratik bir Git-yerel kurulum şu üç koşulu sağlar:

1. Spesifikasyon depoda metin dosyasıdır.
2. Değişiklikler branch, commit, PR ve merge ile akar.
3. Mock, test, codegen ve dokümantasyon merge edilen dosyadan üretilir.

API’leri Git’te tasarlamak neden işe yarar?

Kodunuz için Git’e güveniyorsunuz. API sözleşmeniz de aynı seviyede yönetilmelidir.

1. Geçmiş görünür olur

“cursor sayfalama parametresi ne zaman eklendi?” sorusunun cevabı git log ile bulunur.

git log -p -- api/openapi.yaml

Commit mesajı, yazar, tarih ve değişikliğin tam diff’i birlikte görünür. Ekran görüntüsü veya manuel değişiklik günlüğü aramanız gerekmez.

2. Sorumluluk izlenebilir olur

Bir alan adının neden böyle seçildiğini anlamak için:

git blame api/openapi.yaml

Her satırın kim tarafından, hangi commit ile eklendiğini görürsünüz. İlgili PR’a gidip tasarım tartışmasını okuyabilirsiniz.

3. Geri alma ucuzlar

Kötü bir API tasarımı merge edildiyse:

git revert <commit-sha>

Sözleşme önceki haline döner. Mock, dokümantasyon, istemciler ve testler de bu dosyadan yeniden üretildiği için ayrı sistemlerde manuel temizlik yapmanız gerekmez.

4. İnceleme tasarım aşamasında yapılır

Pull request, API tasarımını kod yazılmadan önce tartışmak için doğal yerdir. İnceleyiciler:

• yeni zorunlu alanları,
• enum değişikliklerini,
• status code seçimlerini,
• adlandırma tutarlılığını,
• bozan değişiklikleri

satır satır yorumlayabilir.

5. Tek doğruluk kaynağı oluşur

Sözleşme main dalındaki tek dosya olduğunda, frontend, backend, QA ve dokümantasyon aynı tanımı okur. Bu, Git tabanlı API spesifikasyonu iş akışının temel avantajıdır.

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

Uygulanabilir döngü şu şekildedir:

1. Sözleşmeyi tasarla.
2. Küçük bir commit oluştur.
3. Pull request aç.
4. API tasarımını incelet.
5. Merge et.
6. Uygulamayı sözleşmeye göre geliştir.

Yani uygulama, sözleşme merge edildikten sonra gelir.

Örneğin bir kullanıcının faturalarını listeleyen endpoint ekleyelim.

git checkout -b feat/api-invoices-list

Ardından OpenAPI dosyasına yeni yolu ekleyin:

# api/openapi.yaml
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ı

Değişikliği odaklı bir commit ile kaydedin:

git add api/openapi.yaml
git commit -m "GET /users/{userId}/invoices sözleşmesini ekle"
git push origin feat/api-invoices-list

Pull request açtığınızda inceleyiciler şunları tartışabilir:

• Yol adı doğru mu?
• operationId tutarlı mı?
• status enum değerleri yeterli mi?
• 404 doğru hata kodu mu?
• Sayfalama gerekli mi?
• Yanıt şeması mevcut standartlarla uyumlu mu?

Bu tartışma tek satır backend kodu yazılmadan yapılır. PR onaylanıp merge edildiğinde, main dalındaki sözleşme artık yeni endpoint’i içerir. Uygulama bu sözleşmeye bağlı olarak geliştirilir. Bu, Önce Şartname API geliştirme yaklaşımının pratik karşılığıdır.

API sözleşmeleri için dallanma stratejisi

Sözleşme değişikliklerini küçük tutun. İdeal olarak her PR tek bir endpoint, tek bir şema değişikliği veya tek bir davranış değişikliği içermelidir.

Dal adlarında niyeti açıkça gösterin:

Değişiklik Türü	Dal Öneki	Örnek	İnceleme Ağırlığı
Yeni endpoint	feat/api-	feat/api-invoices-list	Standart
Ekleyici alan	feat/api-	feat/api-invoice-currency	Hafif
Bozan değişiklik	break/api-	break/api-remove-legacy-id	Ağır, onay gerektirir
Spesifikasyon hatası	fix/api-	fix/api-status-enum-typo	Hafif
Yalnızca düzenleme	chore/api-	chore/api-reorder-schemas	Hafif

Bu önekler hem insanlar hem de CI için sinyal üretir. Örneğin break/api- ile başlayan bir dal, inceleyicilere değişikliğin tüketicileri etkileyebileceğini söyler.

Dallanma modeli için çoğu API ekibinde trunk-based development daha uygundur:

Model	En Uygun Olduğu Durum	API Açısından Sonuç
Trunk-based	Sürekli teslimat, küçük ve orta ekipler	Küçük diff’ler, daha az merge çakışması
Gitflow	Planlı sürümler, regüle dağıtım	Uzun ömürlü dallar, daha büyük merge riskleri

API spesifikasyonları YAML veya JSON olduğu için uzun süreli dallarda çakışma riski yüksektir. Bu yüzden kısa ömürlü branch’ler ve küçük PR’lar tercih edin.

Pull request’lerde API tasarımını nasıl incelemelisiniz?

Bir OpenAPI PR’ı sadece sözdizimi kontrolü değildir; tasarım incelemesidir. İnceleme sırasında şu kontrol listesini kullanın.

Bozan değişiklik var mı?

Aşağıdakiler bozan değişiklik olabilir:

• Alan silmek
• Zorunlu alan eklemek
• Response tipini daraltmak
• Path veya query parametresini yeniden adlandırmak
• Enum’dan değer kaldırmak
• Status code davranışını değiştirmek

Ekleyici değişiklikler genellikle daha güvenlidir. Örneğin enum’a yeni değer eklemek çoğu durumda geriye uyumludur:

parameters:
  - name: status
    in: query
    schema:
      type: string
-     enum: [draft, open, paid, void]
+     enum: [draft, open, paid, void, uncollectible]

Buna karşılık void değerini kaldırmak, bu değeri gönderen istemcileri bozabilir.

Adlandırma tutarlı mı?

Şunları kontrol edin:

• Koleksiyon path’leri çoğul mu?
• operationId formatı mevcut API ile uyumlu mu?
• Hata yanıtları aynı şemayı mı kullanıyor?
• Tarih alanları aynı formatta mı?
• ID alanları aynı adlandırma stilini mi izliyor?

Diff okunabilir mi?

YAML dosyalarında rastgele yeniden sıralama gerçek değişikliği gizler. Şu kuralları uygulayın:

• Anahtar sırasını standartlaştırın.
• Yeni path’leri tahmin edilebilir konuma ekleyin.
• Otomatik formatter kullanıyorsanız ekip genelinde aynı konfigürasyonu kullanın.
• Büyük yeniden düzenlemeleri özellik değişikliklerinden ayrı PR yapın.

PR açıklamasını standartlaştırın

API değişiklikleri için PR şablonu kullanabilirsiniz:

## API değişikliği

- Tür: feat / fix / break / chore
- Etkilenen endpoint:
- Bozan değişiklik var mı? Evet / Hayır
- Versiyon etkisi:
- Dokümantasyon etkisi:
- Test planı:

Bu, incelemeyi hızlandırır ve kritik soruların atlanmasını engeller.

Tasarımdan geliştirmeye geçiş

Sözleşme main dalına merge edildiğinde, downstream yapıtlar bu dosyadan üretilmelidir.

1. Codegen

openapi-generator gibi araçlarla istemci SDK’ları, tipler veya sunucu iskeletleri üretebilirsiniz.

Örnek:

openapi-generator-cli generate \
  -i api/openapi.yaml \
  -g typescript-fetch \
  -o generated/client

Backend tarafında iş mantığını siz yazarsınız; ancak request ve response şekilleri sözleşmeden türetilir.

2. Mock sunucusu

Mock sunucusu OpenAPI dosyasını okuyarak endpoint’ler için örnek yanıtlar döndürür. Bu sayede frontend geliştiricileri backend tamamlanmadan çalışmaya başlayabilir.

Basit akış:

git pull origin main
mock-server --spec api/openapi.yaml

Frontend ekibi artık sözleşmeye göre geliştirme yapabilir.

3. Sözleşme testleri

Sözleşme testleri çalışan API’nin OpenAPI dosyasıyla uyumlu olup olmadığını doğrular.

Kontrol edilen tipik durumlar:

• Response status code sözleşmede var mı?
• Response body şemaya uyuyor mu?
• Zorunlu alanlar dönüyor mu?
• Alan tipleri doğru mu?
• Hata yanıtları beklenen formatta mı?

CI’da bu testler başarısız olursa build kırılmalıdır. Böylece spesifikasyon/kod sapması production problemi olmadan yakalanır.

4. Dokümantasyon

Referans dokümantasyonu elle yazmak yerine OpenAPI dosyasından üretin. Sözleşme değiştiğinde dokümantasyon da aynı commit veya pipeline içinde güncellenir.

Temel kural:

Mock, istemci, test ve dokümantasyon elle değil, merge edilmiş spesifikasyondan üretilmelidir.

Ölçeklenebilir ekip kuralları

Ekip büyüdükçe Git-yerel iş akışının sürdürülebilir olması için kurallar gerekir.

1. Tek dosya mı, çok dosya mı?

Küçük API’lerde tek openapi.yaml yeterlidir. Endpoint sayısı arttığında dosyayı bölmek daha okunabilir olur.

Örnek yapı:

api/
  openapi.yaml
  paths/
    users.yaml
    invoices.yaml
  schemas/
    User.yaml
    Invoice.yaml
    Error.yaml

Build aşamasında bu dosyaları tek spesifikasyonda birleştirebilirsiniz.

2. Versiyonlamayı bilinçli yapın

OpenAPI info.version alanını anlamlı değişikliklerde güncelleyin.

Genel yaklaşım:

• Patch: açıklama, örnek veya typo düzeltmesi
• Minor: geriye uyumlu yeni endpoint veya alan
• Major: bozan değişiklik

Bozan değişikliklerde çoğu zaman yeni yol öneki gerekir:

/v1/invoices
/v2/invoices

3. CHANGELOG tutun

Git geçmişi detaylıdır ama her zaman okunabilir değildir. API tüketicileri için CHANGELOG.md daha kullanışlıdır.

Örnek:

## 2.1.0

- `GET /users/{userId}/invoices` endpoint'i eklendi.
- `Invoice.status` enum'una `uncollectible` değeri eklendi.

## 2.0.0

- `legacyId` alanı kaldırıldı.
- Fatura endpoint'leri `/v2` altına taşındı.

4. CODEOWNERS ile koruyun

API sözleşmesini değiştiren PR’larda API sorumlularından onay isteyin.

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

Bu, iyi niyetli ama tutarsız tasarımların merge edilmesini engeller.

5. CI’da lint çalıştırın

Spectral gibi bir OpenAPI linter ile stil ve tutarlılık hatalarını PR aşamasında yakalayın.

# .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

Lint ve CODEOWNERS birlikte kullanıldığında her sözleşme değişikliği hem otomatik kontrolden hem de insan incelemesinden geçer.

Yaygın tuzaklar ve nasıl kaçınılır?

Spesifikasyon/kod sapması

Sorun: OpenAPI dosyası bir şey söyler, çalışan API başka bir şey döndürür.

Çözüm:

• CI’da sözleşme testleri çalıştırın.
• Response’ları şemaya göre doğrulayın.
• Build’i sapma durumunda başarısız kılın.
• İstemci ve server tiplerini spesifikasyondan üretin.

Devasa PR’lar

Sorun: Tek PR’da 20 endpoint değişirse gerçek inceleme yapılamaz.

Çözüm:

• PR başına bir endpoint veya mantıksal değişiklik hedefleyin.
• Refactor ve davranış değişikliğini ayırın.
• Büyük API tasarımlarını küçük branch’lere bölün.

Elle yazılmış yapıtlar

Sorun: Elle yazılan istemci, mock veya dokümantasyon zamanla spesifikasyondan ayrılır.

Çözüm:

• Client SDK’ları üretin.
• Mock sunucusunu spesifikasyondan başlatın.
• Dokümantasyonu OpenAPI’dan üretin.
• Elle yazılmış API yapıtlarını “smell” olarak değerlendirin.

YAML merge çakışmaları

Sorun: İki uzun ömürlü branch aynı dosyayı yeniden düzenler ve Git çakışmaları büyür.

Çözüm:

• Kısa ömürlü branch kullanın.
• Dosyaları kaynak veya domain bazında bölün.
• Anahtar sırasını sabit tutun.
• Büyük yeniden sıralamaları ayrı PR’da yapın.

Ortak prensip şudur: değişiklikleri küçük tutun, yapıtları spesifikasyondan üretin, CI ile sözleşmeyi zorunlu kılın.

Apidog nerede devreye giriyor?

Git-yerel bir API iş akışını yalnızca metin editörü ve CLI ile yürütebilirsiniz. Ancak birçok ekip, Git’i doğruluk kaynağı olarak korurken görsel bir tasarım arayüzü de ister. Apidog’un Önce Şartname Modu bu ihtiyaca yöneliktir.

Önce Şartname Modu, OpenAPI dosyasını Git deponuzda tutar ve iki yönlü senkronizasyon sağlar. Sözleşmeyi Apidog’un görsel tasarımcısında veya kendi editörünüzde düzenleyebilirsiniz; her iki durumda da depodaki dosya merkezde kalır.

Bu modelde:

• Git ana doğruluk kaynağıdır.
• Branch, PR ve geçmiş normal şekilde çalışır.
• GUI, sözleşmeye bakan bir tasarım yüzeyi olur.
• Mock, test ve dokümantasyon akışları spesifikasyona bağlanabilir.

Kurulum detayları için Önce Şartname Modu belgelerine bakabilirsiniz.

Sıkça Sorulan Sorular

Git-yerel API tasarımı sadece OpenAPI için mi geçerlidir?

Hayır. Bu disiplin metin tabanlı tüm sözleşme formatları için çalışır. OpenAPI en yaygın örnektir, ancak aynı yaklaşım AsyncAPI, gRPC .proto dosyaları veya GraphQL SDL için de uygulanabilir. Önemli olan sözleşmenin diff alınabilir, branch’lenebilir ve review edilebilir bir metin dosyası olmasıdır.

Git-yerel iş akışında bozan değişiklikleri nasıl ele almalıyım?

Bozan değişiklikleri görünür yapın:

• break/api- dal öneki kullanın.
• Major versiyonu artırın.
• CODEOWNERS ile sorumlu onayı zorunlu kılın.
• Mümkünse eski endpoint’i hemen silmek yerine deprecate edin.
• PR açıklamasında etkilenen tüketicileri belirtin.

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

Çoğu durumda evet. Aynı ekip API sözleşmesine ve uygulamaya sahipse, spesifikasyon ve kodun aynı repoda olması işleri basitleştirir. Tek PR içinde sözleşme, handler ve test güncellenebilir.

Ayrı repo şu durumlarda mantıklı olabilir:

• API birçok bağımsız ekip tarafından tüketiliyorsa,
• sözleşme ayrı versiyonlanıyorsa,
• merkezi bir platform ekibi API sözleşmesini yönetiyorsa.

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

CI’a sözleşme testleri ekleyin. Çalışan API’ye gerçek istekler gönderin ve yanıtları kaydedilen OpenAPI dosyasına göre doğrulayın. Sapma varsa build başarısız olsun. Buna codegen ve mock üretimini de eklediğinizde sözleşme, pipeline tarafından sürekli doğrulanır.

Sonuç

Git-yerel API tasarımı bir ürün değil, bir çalışma disiplinidir. API sözleşmesini kaynak kodu gibi yönetirsiniz: branch açar, küçük commit’ler yapar, pull request’te inceler, main dalına merge eder ve downstream yapıtları bu dosyadan üretirsiniz.

Başlamak için minimum uygulama şudur:

1. OpenAPI dosyanızı repoya taşıyın.
2. API değişiklikleri için küçük branch’ler kullanın.
3. PR incelemesini zorunlu yapın.
4. CI’da lint çalıştırın.
5. Mock, codegen, test ve dokümantasyonu spesifikasyondan üretin.

Bu kurallar birlikte çalıştığında Git geçmişiniz API’nizin nasıl büyüdüğünün eksiksiz kaydı haline gelir. Görsel bir tasarım yüzeyi de istiyorsanız, Apidog’daki Önce Şartname Modunu deneyebilir ve Git-yerel iş akışınıza nasıl uyduğunu görebilirsiniz.