Vibe Coding’de Şema-Önce API Geliştirme: AI’ın Endpoint Uydurmasını Önleme

Vibe coding şema önce API yaklaşımı, yapay zekâ ajanın uygulama ile sunucu arasındaki arayüzü tahmin ederek üretmesini engeller. AI kodlama araçları hızlıca istemci, endpoint ve veri modeli oluşturabilir; ancak mevcut API hakkında yalnızca parçalı bilgi görüyorsa alan adlarını, hata formatını veya sayfalama davranışını uydurma riski taşır.

Çözüm daha uzun bir prompt değildir. Endpoint’leri, istek gövdelerini, yanıt şemalarını ve hata durumlarını sürümlenen bir sözleşmede toplamak; sonra ajanın yalnızca bu sözleşmeye dayanarak kod üretmesini sağlamaktır. Böylece “çalışıyor gibi” görünen entegrasyon, ölçülebilir şekilde doğru arayüze bağlanır.

Şema-önce API geliştirme nedir?

Şema-önce yaklaşımında API’nin uygulaması veya istemcisi yazılmadan önce, dışarıdan görünen davranışı bir tanım dosyasında belirtilir. OpenAPI gibi bir tanım; yol, HTTP metodu, parametreler, istek gövdesi, yanıt kodu, veri alanları ve güvenlik bilgisini tek yerde toplayabilir.

Bu dosya yalnızca dokümantasyon değildir. Vibe coding akışında aynı anda şu rolleri üstlenir:

AI ajanın uyması gereken kaynak gerçeklik
İstemci tiplerinin veya modellerinin üretim kaynağı
Mock sunucu ve entegrasyon testinin girdisi
Değişiklik incelemesinde görünen sözleşme farkı
Backend ve frontend ekipleri arasındaki ortak karar kaydı

AI endpoint neden uydurur?

Bir görev “profil sayfasına son siparişleri ekle” diye tanımlandığında, ajan elindeki kod örneklerine bakarak makul görünen bir endpoint seçebilir: /orders/recent, /users/{id}/orders veya /profile/orders. Bunların hiçbiri gerçek API olmayabilir. Aynı belirsizlik alan adlarında da oluşur: createdAt yerine created_at, total yerine amount veya hata için message yerine detail kullanılabilir.

Bu hatalar derleme aşamasında her zaman görünmez. Özellikle mock veri kullanan istemci ekranı doğru görünür; sorun gerçek sunucuya bağlanınca ortaya çıkar. Şema bu tahmini alanı daraltır.

Tek doğruluk kaynağı olarak API sözleşmesi

Depoda birden fazla API bilgisi varsa AI yanlış kaynağa yaslanabilir: eski README, Postman koleksiyonu, örnek JSON, mobil uygulamadaki model veya üretimde artık kullanılmayan endpoint listesi. Önce hangi dosyanın yetkili olduğunu kesinleştirin.

# API sözleşmesi kuralları

Yetkili kaynak: api/openapi.yaml
İstemci modeli: bu şemadan türetilir
Endpoint ekleme: önce şema değişikliği gerekir
Şema dışı alan: kullanılmaz
Hata formatı: components/schemas/ApiError
Kırılma kontrolü: CI içinde sözleşme farkı denetlenir

Bu küçük yönerge, ajanın “mevcut modele benzeyen yeni bir alan ekleyeyim” dürtüsünü sınırlar.

Minimum ama yeterli OpenAPI örneği

İlk sözleşme kusursuz olmak zorunda değildir. Önemli olan en kritik davranışı belirsiz bırakmamasıdır. Aşağıdaki örnek, sipariş listesi için gereken temel kararları görünür kılar:

paths:
  /v1/orders:
    get:
      operationId: listOrders
      parameters:
        - name: cursor
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Sipariş sayfası
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderPage'
        '401':
          $ref: '#/components/responses/Unauthorized'

components:
  schemas:
    OrderPage:
      type: object
      required: [items, nextCursor]
      properties:
        items:
          type: array
          items: { $ref: '#/components/schemas/Order' }
        nextCursor:
          type: [string, 'null']

Bu örnekte endpoint, sayfalama biçimi, başarı yanıtı ve yetkilendirme hatası açıkça tanımlanır. Ajanın listeyi dizi olarak mı, nesne olarak mı döndüreceğini tahmin etmesi gerekmez.

Her endpoint için cevaplanması gereken 8 soru

İşlemin amacı nedir ve operationId nasıl adlandırılır?
Yol ve HTTP metodu nedir?
Kimlik doğrulama veya yetki kuralı nedir?
Hangi path, query veya header parametreleri zorunludur?
İstek gövdesinde hangi alanlar gerekir; hangileri isteğe bağlıdır?
Başarılı yanıt hangi durum kodu ve şema ile döner?
Doğrulama, yetki, bulunamadı ve sunucu hatası nasıl temsil edilir?
İstemcinin tekrar deneme, önbellek veya sayfalama davranışı var mıdır?

Bu soruların birinde “sonra bakarız” cevabı varsa, AI’a kod yazdırmadan önce sözleşmeyi netleştirmek genellikle daha hızlıdır.

Örnek yanıt eklemek neden önemlidir?

Şema alan tiplerini açıklar; örnek yanıt ise iş anlamını taşır. Örneğin status alanının string olması yeterli değildir: hangi değerlerin geldiği, boş olabileceği ve ekranda ne ifade ettiği bilinmelidir.

{
  "items": [
    {
      "id": "ord_92",
      "status": "pending_payment",
      "total": { "amount": 24990, "currency": "TRY" },
      "createdAt": "2026-08-14T14:30:00Z"
    }
  ],
  "nextCursor": null
}

Örnekleri küçük, gerçekçi ve anonim tutun. Gerçek müşteri verisini sözleşmeye veya prompta koymayın.

Hata yanıtını ayrı bir vatandaş yapın

Vibe coding projelerinde en sık görülen API hatalarından biri, başarı modelinin iyi tasarlanıp hata modelinin belirsiz bırakılmasıdır. Sonuçta her ekran farklı bir try/catch deseni üretir; bazıları sunucu mesajını gösterir, bazıları sessizce boş liste döndürür.

Tekrarlanabilir bir hata sözleşmesi tanımlayın:

Makine tarafından okunabilir code
Kullanıcıya doğrudan gösterilmeyen güvenli message
Alan doğrulaması için fieldErrors
İzleme için istek kimliği
Tekrar denenebilirlik işareti

Böylece AI ajanı hata yönetimini her ekranda yeniden icat etmez.

İstemciyi şemadan üretin veya şemaya göre doğrulayın

En sağlam seçenek, mümkünse istemci tiplerini ve API kodunu sözleşmeden üretmektir. Bu mümkün değilse en azından gelen yanıtı çalışma zamanında veya testte şemaya göre doğrulayın. Amaç teknoloji seçmek değil; model sınıfı ile gerçek API arasındaki farkı erken yakalamaktır.

Bir AI ajana şu sınırı koyabilirsiniz:

API istemcisini yalnızca api/openapi.yaml içindeki operasyonlar ve şemalar üzerinden değiştir. Şemada olmayan endpoint veya alan gerekiyorsa kod yazma; sözleşme değişikliği önerisi hazırla.

Kırılma değişikliğini nasıl yakalarsınız?

Her değişiklik eşit risk taşımaz. Alan eklemek çoğu zaman geriye uyumludur; zorunlu alanı kaldırmak, tür değiştirmek veya hata biçimini değiştirmek istemcileri kırabilir. Sözleşme farkını kod farkı gibi inceleyin.

Değişiklik	Risk	Önerilen karar
İsteğe bağlı yanıt alanı ekleme	Düşük	Örnek ve istemci davranışını kontrol et
Zorunlu istek alanı ekleme	Yüksek	Yeni sürüm veya geçiş planı oluştur
Alan türü değiştirme	Yüksek	Kırılma olarak değerlendir
Enum değerini kaldırma	Orta/yüksek	Eski istemciyi ve ekran eşlemesini test et
Hata gövdesini değiştirme	Orta	Ortak hata işleyicisini regresyon testine ekle

AI görev paketine sözleşmeyi nasıl eklemelisiniz?

Tüm API tanımını konuşmaya yapıştırmak yerine, ajana sözleşme dosyasını okuma sorumluluğu verin ve görevle ilgili operasyonları belirtin.

Görev: Sipariş geçmişi ekranını ekle.

Kaynak gerçeklik:
- api/openapi.yaml
- Operasyon: listOrders
- Şemalar: OrderPage, Order, ApiError

Kabul ölçütleri:
- nextCursor null ise "daha fazla yükle" gösterme.
- 401 yanıtı oturum yenileme akışına gider.
- fieldErrors kullanıcıya ham JSON olarak gösterilmez.
- Şema dışı endpoint, alan veya enum değeri eklenmez.

Doğrulama:
- İlgili sözleşme testi çalışır.
- İstemci tipleri derlenir.
- Değişen dosyalar ve şema bağımlılıkları özetlenir.

Mock sunucu doğru güveni nasıl verir?

Mock, ekran geliştirmeyi hızlandırır; fakat yalnızca mutlu yolu taklit ediyorsa sahte güven üretir. Mock verisine en az bir boş liste, bir yetkisiz yanıt, bir doğrulama hatası ve sayfalı yanıt ekleyin. Bu örnekler sözleşmeden türemelidir; elle hazırlanmış farklı bir JSON dosyasından değil.

Mock ile üretim arasındaki farkı azaltmanın en iyi yolu, aynı şema ve örnekleri iki tarafta da kullanmaktır.

Sürümleme ve uyumluluk kapısı

API sürümü yalnızca URL’ye /v2 eklemek değildir. Önce hangi tüketicilerin etkilendiğini ve eski istemcinin ne kadar süre destekleneceğini belirleyin. Küçük değişiklikler için sürümlenmiş sözleşme + uyumluluk testi genellikle daha görünür bir yoldur.

CI kalitenin son kapısı olabilir:

OpenAPI biçimi geçerli mi?
Değişiklik kırılma riski taşıyor mu?
Örnek yanıtlar şemaya uyuyor mu?
İstemci tipleri ve ilgili testler derleniyor mu?
Eski kritik istemci akışları korunuyor mu?

Şema-önce yaklaşımının sınırları

Şema her problemi çözmez. Gecikme, hız limiti, idempotency, sıra dışı yetki kuralları ve iş akışındaki zamanlama gibi davranışlar ek açıklama ve test gerektirir. Şema “şekli” tanımlar; ürün davranışını tamamlamak için örnek, kabul ölçütü ve regresyon senaryosu gerekir.

Bu nedenle şema-önce geliştirmeyi bağlam mühendisliği ve eval-driven development ile birlikte uygulayın. Sözleşme ajana doğru gerçekliği verir; değerlendirme ise bu gerçekliğe uyulduğunu kanıtlar.

20 dakikalık başlangıç planı

5 dakika: En riskli tek endpoint’i seçin ve yol, metot, başarı yanıtı ile hata yanıtını yazın.
5 dakika: Zorunlu alanları, enum değerlerini ve boş/opsiyonel alanları işaretleyin.
5 dakika: Bir başarı, bir boş durum, bir yetki hatası ve bir doğrulama hatası örneği ekleyin.
5 dakika: AI görev paketine yetkili sözleşme dosyasını ve “şema dışı alan ekleme” sınırını koyun.

Sonuç

Vibe coding’de API entegrasyonunun en tehlikeli hatası, modelin yanlış olması değil; yanlış varsayımın makul görünmesidir. Şema-önce yaklaşımı bu varsayımı görünür, sürümlenebilir ve test edilebilir hâle getirir.

Bir sonraki entegrasyon görevinizde önce ekranı değil sözleşmeyi açın. Endpoint, örnek yanıt ve hata biçimi netleştiğinde AI ajanı daha az uydurur; siz de daha az düzeltme turu yaparsınız.