Spec-First API Geliştirme Nedir?

Şartname-Öncelikli API Geliştirme: OpenAPI ile Mock, Test ve Dokümantasyon Üretme

Çoğu API hatası kodlama hatası değildir; sözleşme hatasıdır. Frontend userId beklerken backend user_id gönderir ve bu fark genellikle QA aşamasına kadar görünmez. Şartname-öncelikli API geliştirme, API sözleşmesini en sona bırakılan doküman değil, ilk yazılan kaynak haline getirerek bu problemi azaltır.

Apidog'u bugün deneyin

Bu rehberde küçük bir OpenAPI şartnamesi yazacak, ardından sunucu kodu hazır olmadan önce bu dosyadan mock veri, test ve dokümantasyon üreteceksiniz. Bu yaklaşım; şartname odaklı, tasarım-öncelikli veya sözleşme-öncelikli geliştirme olarak da adlandırılır. Temel fikir aynıdır: önce arayüz üzerinde anlaşın, sonra implementasyonu buna göre geliştirin.

Şartname-öncelikli API geliştirme nedir?

Şartname-öncelikli API geliştirme, uç noktayı uygulamadan önce makine tarafından okunabilir bir API sözleşmesi yazmanız anlamına gelir. Bu sözleşme genellikle bir OpenAPI belgesidir ve şunları tanımlar:

• URL yolları
• HTTP metodları
• Query/path parametreleri
• İstek gövdeleri
• Yanıt şemaları
• Durum kodları
• Hata yanıtları

Bu dosya hazır olduğunda API için doğruluk kaynağı olur.

Pratik akış şu şekildedir:

1. OpenAPI şartnamesini yazın.
2. Frontend ekibi bu şartnameden üretilen mock API’ye karşı geliştirme yapar.
3. QA ekibi aynı şartnameye göre test senaryoları oluşturur.
4. Backend ekibi implementasyonu bu sözleşmeye göre geliştirir.
5. CI veya test araçları gerçek yanıtların şartnameyle uyumlu olup olmadığını kontrol eder.

Kod-öncelikli geliştirmede dokümantasyon genellikle implementasyondan sonra gelir ve hızla güncelliğini yitirir. Şartname-öncelikli akışta ise açıklama önce gelir, kod ona uyum sağlar. Böylece entegrasyon hataları projenin başında, düzeltmenin daha ucuz olduğu aşamada yakalanır.

Şartname-öncelikli ve kod-öncelikli yaşam döngüsü

İki yaklaşım da aynı API uç noktalarını üretebilir. Fark, ekiplerin ne zaman paralel çalışabildiği ve hataların ne zaman yakalandığıdır.

Şartname önce hazır olduğunda frontend, backend ve QA aynı dosyaya bakar. Böylece “backend ne dönecek?”, “frontend ne bekliyor?” veya “test hangi davranışı doğrulamalı?” gibi sorular tahmine dönüşmez.

Çalışır bir OpenAPI örneği

Küçük bir /users API’si tasarlayalım. Hedefimiz iki işlem tanımlamak:

• GET /users: kullanıcıları listeler
• POST /users: yeni kullanıcı oluşturur

1. OpenAPI başlığını yazın

openapi: 3.0.3
info:
  title: Users API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1

Bu bölüm OpenAPI sürümünü, API adını, versiyonu ve temel sunucu adresini tanımlar.

2. Paylaşılan User şemasını tanımlayın

components:
  schemas:
    User:
      type: object
      required: [id, email, createdAt]
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type: string
        createdAt:
          type: string
          format: date-time

User şemasını components/schemas altında tanımlamak, aynı veri yapısını farklı endpoint’lerde tekrar tekrar yazmanızı engeller. Daha sonra $ref ile bu şemaya referans verebilirsiniz.

3. GET /users işlemini ekleyin

paths:
  /users:
    get:
      summary: List users
      operationId: listUsers
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        "200":
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"

Bu işlem kullanıcı listesini döndürür. limit query parametresi opsiyoneldir, varsayılan değeri 20dir ve maksimum 100 olabilir.

4. POST /users işlemini ekleyin

paths:
  /users:
    post:
      summary: Create a user
      operationId: createUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email:
                  type: string
                  format: email
                name:
                  type: string
      responses:
        "201":
          description: User created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "400":
          description: Invalid request body

Bu işlem yeni kullanıcı oluşturur. İstek gövdesinde email zorunludur. Başarılı durumda 201, geçersiz istek durumunda 400 döner.

5. Tam OpenAPI dosyası

Aşağıdaki dosya eksiksiz ve geçerli bir küçük API sözleşmesidir:

openapi: 3.0.3
info:
  title: Users API
  version: 1.0.0

servers:
  - url: https://api.example.com/v1

paths:
  /users:
    get:
      summary: List users
      operationId: listUsers
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        "200":
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"

    post:
      summary: Create a user
      operationId: createUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email:
                  type: string
                  format: email
                name:
                  type: string
      responses:
        "201":
          description: User created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "400":
          description: Invalid request body

components:
  schemas:
    User:
      type: object
      required: [id, email, createdAt]
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type: string
        createdAt:
          type: string
          format: date-time

Bu aşamada henüz sunucu kodu yazılmadı. Buna rağmen API sözleşmesi netleşti:

• email zorunlu
• id UUID formatında
• createdAt tarih-saat formatında
• limit en fazla 100
• POST /users başarılı olursa 201
• Geçersiz isteklerde 400

Şartnameden mock veri, test ve dokümantasyon üretin

Şartnameyi önce yazmanın en büyük avantajı, tek dosyadan birden fazla çıktı üretmenizdir.

1. Mock API oluşturun

Mock sunucu OpenAPI dosyasını okur ve şemalara uygun örnek yanıtlar döndürür.

Örneğin frontend şu isteği yapabilir:

GET /users?limit=2

Mock sunucu buna benzer bir yanıt döndürebilir:

[
  {
    "id": "3f4f83b4-6d6f-4ad2-9b3b-7cdb5f7f0e4a",
    "email": "[e-mail]",
    "name": "Example User",
    "createdAt": "2026-06-02T10:15:30Z"
  }
]

format: uuid, format: email ve format: date-time gibi ipuçları, araçların daha gerçekçi örnek veri üretmesine yardımcı olur.

Bu sayede frontend ekibi backend implementasyonunu beklemeden geliştirmeye başlayabilir.

2. Sözleşme testleri yazın

OpenAPI dosyası testler için de referans olur. Testlerin amacı yeni kurallar icat etmek değil, gerçek API’nin sözleşmeye uyup uymadığını doğrulamaktır.

Örnek doğrulamalar:

• POST /users geçerli gövdeyle çağrıldığında 201 dönmeli.
• Yanıt gövdesi User şemasıyla eşleşmeli.
• email eksikse 400 dönmeli.
• GET /users bir dizi dönmeli.
• Dizideki her öğe User şemasına uymalı.

Basit bir test mantığı şu şekilde düşünülebilir:

const response = await fetch("https://api.example.com/v1/users", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    email: "[e-mail]",
    name: "Dev User"
  })
});

expect(response.status).toBe(201);

const body = await response.json();

expect(body).toHaveProperty("id");
expect(body).toHaveProperty("email");
expect(body).toHaveProperty("createdAt");

Gerçek projelerde bu doğrulamaları OpenAPI sözleşmesine göre otomatikleştiren araçlar kullanabilirsiniz.

3. API dokümantasyonu üretin

API referans dokümantasyonu doğrudan OpenAPI dosyasından üretilebilir. Böylece ayrı bir doküman kopyasını elle güncel tutmanız gerekmez.

Aynı YAML dosyası şunları besler:

• Endpoint listesi
• Parametre açıklamaları
• Request body şemaları
• Response body şemaları
• Durum kodları
• Örnek yanıtlar

Bu yaklaşım, şartname-öncelikli geliştirmenin Git-tabanlı bir API iş akışıyla iyi eşleşmesini sağlar. OpenAPI dosyası düz metin olduğu için her değişiklik pull request içinde fark olarak incelenebilir.

Örneğin bir geliştirici email alanını yeniden adlandırırsa veya required listesinden çıkarırsa, bu değişiklik yayınlanmadan önce kod incelemesinde görülebilir.

Apidog'da yapmak

Apidog, bu uçtan uca akışı Şartname-Öncelikli Mod ile destekler. OpenAPI dosyasını yalnızca dışa aktarılan bir çıktı olarak değil, projenin merkezi kaynağı olarak ele alır.

Pratik akış şu şekildedir:

1. /users OpenAPI şartnamesini düzenleyiciye yazın veya yapıştırın.
2. Apidog şartnameyi ayrıştırır.
3. Tanımlanan işlemler için mock sunucu oluşturulur.
4. Frontend ekibi mock endpoint’leri çağırmaya başlar.
5. Dokümantasyon şartnameye göre güncellenir.
6. Backend hazır olduğunda işlemleri gerçek API’ye karşı test olarak çalıştırırsınız.
7. Yanıtların şemalarla eşleşip eşleşmediğini doğrularsınız.

İki yönlü Git senkronizasyonu bu akışı daha güvenli hale getirir. Şartname bir repoda yaşar ve değişiklikler incelenebilir commit’ler olarak takip edilir.

• YAML dosyasını editörünüzde değiştirip gönderdiğinizde Apidog bunu alır.
• Apidog içinde değişiklik yaptığınızda bu değişiklik ekibin inceleyebileceği commit olarak kaydedilir.
• Sözleşme aynı anda iki farklı yerde ayrı ayrı yaşamaz.

Şartname-öncelikli yaklaşımın tasarım-öncelikli yaklaşımla nerede ayrıldığını daha detaylı görmek için Apidog'da şartname-öncelikli ve tasarım-öncelikli karşılaştırmasına bakabilirsiniz.

Şartname-öncelikli kontrol listesi

Bir API şartnamesini geliştirmeye hazır kabul etmeden önce şu kontrolleri yapın:

• [ ] OpenAPI dosyası şemaya karşı hatasız doğrulanıyor.
• [ ] Her endpoint en az bir başarılı yanıt belirtiyor.
• [ ] Her endpoint en az bir hata yanıtı belirtiyor.
• [ ] Paylaşılan veri yapıları components/schemas altında tanımlanıyor.
• [ ] Ortak şemalar kopyalanmak yerine $ref ile kullanılıyor.
• [ ] Zorunlu alanlar required listesinde yer alıyor.
• [ ] uuid, email, date-time gibi formatlar uygun yerlerde belirtiliyor.
• [ ] Şartname dosyası Git’e kaydediliyor.
• [ ] Değişiklikler pull request üzerinden inceleniyor.
• [ ] Şartnameden mock sunucu çalışıyor.
• [ ] Frontend mock API’ye erişebiliyor.
• [ ] Sözleşme testleri gerçek backend yanıtlarını doğruluyor.
• [ ] Yayınlanan dokümantasyon aynı OpenAPI dosyasından üretiliyor.

Bu kutular işaretlendiğinde ekipler ayrı varsayımlar yerine tek bir sözleşmeye göre paralel çalışabilir.

Sıkça sorulan sorular

Şartname-öncelikli API geliştirme tasarım-öncelikli ile aynı mıdır?

Çoğunlukla evet. “Tasarım-öncelikli” ve “sözleşme-öncelikli” aynı ilkeyi anlatır: implementasyondan önce arayüzü tanımlamak.

“Şartname-öncelikli” daha somut bir ifadedir, çünkü başlangıç noktası belirli bir dosyadır: OpenAPI şartnamesi. Pratikte bu terimler çoğu ekipte birbirinin yerine kullanılır.

YAML’ı elle yazmak zorunda mıyım?

Hayır. Şartnameyi görsel bir düzenleyicide oluşturup YAML’ın araç tarafından üretilmesini sağlayabilirsiniz. İsterseniz doğrudan YAML da yazabilirsiniz.

Önemli olan formatı nasıl yazdığınız değil, sözleşmenin koddan önce var olması ve ekip tarafından kabul edilmesidir. Birçok ekip ikisini birlikte kullanır: ilk taslağı görsel olarak çıkarır, inceleme sırasında YAML üzerinde düzenleme yapar.

Şartnamenin ve kodun birbirinden sapmasını nasıl önleyebilirim?

Şartnameyi doğruluk kaynağı yapın ve bunu süreçle destekleyin:

• OpenAPI dosyasını Git’te tutun.
• Değişiklikleri pull request ile inceleyin.
• CI sürecinde sözleşme testleri çalıştırın.
• Gerçek yanıt şemayla eşleşmezse build’i başarısız yapın.
• Mock, test ve dokümantasyonu aynı dosyadan üretin.

İki yönlü senkronizasyon kullanıyorsanız, araç içindeki değişiklikler ile repodaki değişiklikler uzlaştırılmış kalır. Bu da sözleşme sapmasının en yaygın nedenlerinden birini ortadan kaldırır.

Sonuç

Şartname-öncelikli API geliştirme küçük bir sıralama değişikliğidir: önce sözleşmeyi yazın, sonra implementasyonu geliştirin. Ancak etkisi büyüktür. Frontend, backend ve QA aynı OpenAPI dosyasına göre çalıştığında entegrasyon daha erken başlar, hatalar daha erken yakalanır ve dokümantasyon güncel kalır.

Bu akışı denemek isterseniz Apidog’da Şartname-Öncelikli Modu açın ve OpenAPI dosyanızı deponuza bağlayın.