Bruno Önce İstek mi Tasarım mı? Tasarım Odaklı Bir Araca İhtiyacınız Olduğunda

Bruno isteğe öncelikli bir API istemcisidir: HTTP istekleri oluşturur, düzenler, gönderir ve bunları .bru dosyaları olarak Git’te sürümlersiniz. Bu yaklaşım mevcut API’leri keşfetmek, hızlı test etmek ve istek koleksiyonlarını kodla birlikte yönetmek için güçlüdür.

Apidog'u bugün deneyin

Ancak “isteğe öncelikli” ve “tasarıma öncelikli” aynı problemi çözmez. İsteğe öncelikli yaklaşım şu soruyla başlar: Bu endpoint’i nasıl çağırırım? Tasarıma öncelikli yaklaşım ise şunu sorar: Bu endpoint, sunucu kodu yazılmadan önce nasıl tanımlanmalı? Yeni API geliştiren, birden fazla ekibin aynı sözleşmeye bağlı çalıştığı veya public API yayınlayan ekiplerde fark burada ortaya çıkar.

İsteğe öncelikli ve tasarıma öncelikli: hızlı karşılaştırma

Aşağıdaki tabloyu araç seçimi için pratik bir kontrol listesi gibi kullanabilirsiniz.

Boyut	İsteğe Öncelikli (Bruno)	Tasarıma Öncelikli (OpenAPI’ye özgü)
Başlangıç noktası	Gönderilebilir HTTP isteği	OpenAPI sözleşmesi
En uygun kullanım	Mevcut API’leri keşfetmek ve test etmek	Koddan önce yeni/paylaşılan API tasarlamak
Doğruluk kaynağı	İstek koleksiyonu	API belirtimi
Ekipler arası inceleme	Endpoint’ler oluştuktan sonra	Sunucu kodu yazılmadan önce
Görsel tasarım yüzeyi	Varsayılan olarak yok	Görsel tasarımcı + şema düzenleyici
Sapma riski	Koleksiyon gerçek API’nin gerisinde kalabilir	Belirtim tek sözleşme olarak kalır
Git hikayesi	Güçlü: düz metin .bru dosyaları	Araç belirtimi Git ile senkronize ediyorsa güçlü

Kısaca:

• API zaten çalışıyorsa ve amacınız onu çağırmaksa, isteğe öncelikli yaklaşım hızlıdır.
• API henüz tasarlanıyorsa veya başka ekipler bu API’ye bağımlı olacaksa, tasarıma öncelikli yaklaşım daha güvenlidir.

Bruno’nun isteğe öncelikli modeli nasıl çalışır?

Bruno’nun modeli nettir:

1. Bir koleksiyon oluşturursunuz.
2. HTTP istekleri eklersiniz.
3. İstekler düz metin .bru dosyaları olarak saklanır.
4. Dosyaları Git’e koyarsınız.
5. İstekleri lokal olarak çalıştırır, test eder ve PR içinde incelersiniz.

Bu yüzden Bruno, API istemcisinin kod tabanının doğal bir parçası gibi davranmasını isteyen ekipler için uygundur. Zorunlu bulut hesabı, tescilli senkronizasyon veya devre dışı bırakılması gereken arka plan telemetrisi olmadan çalışır. Bu da birçok ekibin benimsediği Git’e özgü API iş akışının temelidir.

Bruno özellikle şu işler için uygundur:

• Çalışan bir API’ye istek gönderip yanıtı incelemek
• Endpoint davranışını hızlıca doğrulamak
• Ortam değişkenleriyle farklı ortamları test etmek
• İstek öncesi/sonrası betiklerle basit otomasyon yapmak
• İstek koleksiyonlarını Git içinde sürümlemek
• API keşfini lokal ve dosya tabanlı tutmak

Örneğin mevcut bir endpoint’i doğrulamak istiyorsanız isteğe öncelikli akış yeterlidir:

GET https://api.example.com/users/123
Authorization: Bearer {{token}}

Ardından beklenen yanıtı kontrol edersiniz:

{
  "id": "123",
  "name": "Ada Lovelace",
  "email": "[e-mail]"
}

Bu senaryoda amaç API sözleşmesini tasarlamak değil, çalışan API’nin doğru davranıp davranmadığını görmektir.

Daha geniş platformlarla karşılaştırma için bu Bruno alternatif değerlendirmesine de bakabilirsiniz.

Tasarım veya sözleşme katmanı olmadığında ne olur?

İsteğe öncelikli araçlar mevcut API’lerle çalışırken hızlıdır. Ancak API henüz yoksa veya birden fazla ekip API’nin şeklinde anlaşmak zorundaysa sınırlamalar başlar.

1. Tasarım örnek isteklerin içine sıkışır

İsteğe öncelikli araçlarda endpoint’ler çoğunlukla tek tek istekler olarak modellenir. Bu, kaynakları, şemaları, hata tiplerini ve response yapılarını merkezi bir sözleşme olarak görmeyi zorlaştırır.

Örneğin aşağıdaki istek bir kullanıcı oluşturma örneği gösterir:

POST /users
Content-Type: application/json

{
  "name": "Ada Lovelace",
  "email": "[e-mail]"
}

Ancak bu örnek tek başına şu soruları net cevaplamaz:

• email zorunlu mu?
• name maksimum kaç karakter olabilir?
• Başarısız durumda hata formatı nedir?
• 201 dışında hangi response’lar dönebilir?
• Aynı schema başka endpoint’lerde tekrar kullanılacak mı?

Tasarıma öncelikli yaklaşımda bu bilgiler örnek isteklerde değil, OpenAPI sözleşmesinde tanımlanır.

2. Koleksiyon API’den geride kalabilir

İstek koleksiyonu doğruluk kaynağı olduğunda yalnızca birinin daha önce çağırdığı endpoint’leri ve örnekleri yansıtır. Gerçek API değiştiğinde koleksiyon otomatik olarak sözleşme seviyesinde sizi uyarmayabilir.

Örneğin backend ekibi şu değişiklikleri yapabilir:

• Yeni zorunlu alan eklemek
• Bir query parametresini kaldırmak
• Response schema’sını değiştirmek
• Validation kurallarını sıkılaştırmak

Koleksiyon güncellenmezse sapma oluşur. Bu sapma genellikle ancak test kırıldığında veya entegrasyon hatası çıktığında görünür.

3. Koddan önce inceleme zorlaşır

Bir istek klasörünü incelemek, endpoint’lerin bugün nasıl çağrıldığını gösterir. Ancak API’nin gelecekte nasıl davranması gerektiğini bildirime dayalı, merkezi ve review edilebilir bir sözleşme olarak sunmaz.

Tasarım incelemesi yapan ekipler için OpenAPI şu tip kontrolleri kolaylaştırır:

• Endpoint isimleri tutarlı mı?
• Resource yapısı doğru mu?
• Request ve response schema’ları yeniden kullanılabilir mi?
• Hata formatı tüm API’de standart mı?
• Breaking change var mı?

Bruno kötü bir araç olduğu için değil, isteğe öncelikli olduğu için bu tasarım aşamasında doğal olarak sınırlanır.

Tasarıma öncelikli yaklaşım ne zaman daha doğru seçimdir?

Tasarıma öncelikli yaklaşım özellikle şu üç senaryoda öne çıkar.

1. Greenfield API geliştiriyorsanız

Henüz endpoint yoksa, önce istek koleksiyonu oluşturmak yerine sözleşmeyi yazmak daha sağlıklıdır.

Örnek OpenAPI başlangıcı:

openapi: 3.0.3
info:
  title: Users API
  version: 1.0.0
paths:
  /users:
    post:
      summary: Kullanıcı oluşturur
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: Kullanıcı oluşturuldu
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    CreateUserRequest:
      type: object
      required:
        - name
        - email
      properties:
        name:
          type: string
        email:
          type: string
          format: email
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email

Bu sözleşmeden daha sonra şunları üretebilir veya yönetebilirsiniz:

• Mock API
• Dokümantasyon
• Sunucu taslakları
• İstemci SDK’ları
• Contract testleri

2. Birden fazla ekip aynı API’ye bağlıysa

Backend, frontend, mobil ve QA ekipleri aynı endpoint’e bağımlıysa OpenAPI sözleşmesi ortak anlaşma noktası olur.

Pratik akış:

1. API sözleşmesini OpenAPI ile tanımlayın.
2. Frontend ve backend ekipleri sözleşmeyi PR’da inceleyin.
3. Mock server ile frontend geliştirmesini başlatın.
4. Backend uygulamasını aynı sözleşmeye göre geliştirin.
5. Uygulama tamamlandığında gerçek endpoint’i sözleşmeye karşı doğrulayın.

Bu şekilde frontend ekibi gerçek endpoint’in hazır olmasını beklemeden çalışabilir.

3. Public API yayınlıyorsanız

Harici geliştiriciler API’nize bağımlı olduğunda dokümantasyon, kararlılık ve breaking change yönetimi ürünün parçası haline gelir.

OpenAPI sözleşmesi burada şunları sağlar:

• Oluşturulmuş referans dokümantasyonu
• Tutarlı endpoint ve schema yapısı
• Sürümleme disiplini
• Breaking change’leri daha görünür hale getirme
• Onboarding sürecini hızlandırma

Ortak nokta şudur: API, koddan önce üzerinde anlaşılması gereken paylaşılan bir arayüzse tasarıma öncelikli yaklaşım daha iyi çalışır.

Apidog ile tasarıma öncelikli ve Spec-First çalışma

Apidog tasarıma öncelikli API geliştirme için tasarlanmıştır. Buradaki önemli nokta, OpenAPI’ye özgü ve Git dostu bir akıştan vazgeçmeden çalışabilmenizdir.

Apidog’da aynı API projesi üzerinde iki şekilde çalışabilirsiniz:

1. Görsel tasarımcı ile çalışma

   • Endpoint’leri tanımlarsınız.
   • Request ve response schema’larını oluşturursunuz.
   • Yeniden kullanılabilir bileşenleri yönetirsiniz.
   • YAML’i elle yazmadan API sözleşmesini şekillendirirsiniz.

2. Spec-First Modu ile çalışma

   • OpenAPI belgesini doğrudan kod düzenleyicide yazarsınız.
   • Belirtim doğruluk kaynağı olur.
   • Görsel tasarım yüzeyi ve OpenAPI belgesi senkronize kalır.

Bu sayede bir backend mühendisi ham OpenAPI üzerinde çalışırken, ürün veya frontend tarafı aynı sözleşmeyi görsel tasarımcı üzerinden inceleyebilir.

Örnek pratik akış:

OpenAPI spec değişikliği
        ↓
Git PR
        ↓
API tasarım incelemesi
        ↓
Mock / dokümantasyon / test
        ↓
Backend uygulaması
        ↓
Sözleşmeye göre doğrulama

Spec-First Modu ayrıca çift yönlü Git senkronizasyonunu destekler. Yani OpenAPI dosyanız deponuzda gerçek bir dosya olarak yaşar, değişiklikler iki yönde akar ve API tasarımınız kodunuzla aynı PR ve review sürecinden geçer.

Bu, Bruno kullanıcılarının değer verdiği Git’e özgü yaklaşımı istek koleksiyonuna değil, doğrudan API sözleşmesine uygular. Mekanik detaylar için Spec-First Modu dokümantasyonuna bakabilirsiniz.

Sonuçta tek bir akışta iki ihtiyacı karşılayabilirsiniz:

• API henüz yokken önce sözleşmeyi tasarlamak
• API yayındayken endpoint’leri isteğe öncelikli bir istemci gibi test etmek

Bu iki modelin nerede kesiştiğini daha ayrıntılı görmek için Apidog’da belirtim öncelikli ve tasarım öncelikli yaklaşım makalesine bakabilirsiniz.

Hangi ekip için hangi yaklaşım daha uygun?

Araç seçimini kişisel tercihe göre değil, API yaşam döngüsüne göre yapın.

Küçük ekip veya bireysel geliştirici

Eğer çoğunlukla mevcut API’leri tüketiyor ve test ediyorsanız isteğe öncelikli yaklaşım yeterlidir.

Uygun senaryo:

• Üçüncü taraf API’leri çağırıyorsunuz.
• Kendi backend’inizi hızlıca manuel test ediyorsunuz.
• API sözleşmesi ayrı bir ekip tarafından yönetilmiyor.
• Git içinde lokal istek koleksiyonu tutmak istiyorsunuz.

Bu durumda Bruno’nun düz metin ve lokal öncelikli modeli pratiktir.

Kendi API’lerini yayınlayan büyüyen ekip

İkinci bir ekip API’nize bağımlı olduğunda istek koleksiyonu tek başına yeterli olmamaya başlar.

Bu aşamada OpenAPI sözleşmesi size şunları kazandırır:

• Koddan önce API review
• Frontend/backend paralel geliştirme
• Daha net dokümantasyon
• Daha az entegrasyon hatası
• Breaking change görünürlüğü

Bu, birçok ekip için isteğe öncelikliden tasarıma öncelikliye geçiş noktasıdır.

Public API veya çok sayıda internal API yöneten olgun ekip

Public API yayınlıyorsanız veya kurum içinde birçok API yönetiyorsanız tasarıma öncelikli yaklaşım pratikte gereklidir.

Bu seviyede belirtim yalnızca teknik doküman değil, aynı zamanda:

• Yönetişim aracı
• Dokümantasyon kaynağı
• Entegrasyon sözleşmesi
• Test referansı
• Sürümleme temeli

haline gelir.

Uygulanabilir karar ağacı

Aşağıdaki sorularla hızlı karar verebilirsiniz:

API zaten var mı?
├─ Evet
│  ├─ Sadece keşif/test mi yapıyorsunuz?
│  │  └─ İsteğe öncelikli araç yeterli olabilir.
│  └─ API başka ekipler tarafından da tüketiliyor mu?
│     └─ OpenAPI sözleşmesi ekleyin.
└─ Hayır
   ├─ Birden fazla ekip bu API’ye bağımlı mı?
   │  └─ Tasarıma öncelikli başlayın.
   └─ Public API olacak mı?
      └─ Tasarıma öncelikli başlayın.

En kısa yorum şu: Bruno mevcut API’leri çağırmak için güçlüdür; OpenAPI’ye dayalı tasarıma öncelikli yaklaşım ise API’nin kendisini koddan önce tanımlamak için daha uygundur.

Sıkça Sorulan Sorular

Bruno isteğe öncelikli mi yoksa tasarıma öncelikli mi?

Bruno isteğe önceliklidir. Temel modeli, mevcut API’leri keşfetmek ve test etmek için istek oluşturma, düzenleme ve gönderme üzerine kuruludur. İstekler düz metin dosyaları olarak saklanır. API oluşturulmadan önce OpenAPI sözleşmesi yazmaya odaklanan bir tasarıma öncelikli araç değildir.

Bruno’da tasarıma öncelikli çalışma yapabilir miyim?

Belirtim merkezli bir aracın sunduğu şekilde doğal olarak değil. Bruno, doğruluk kaynağı olarak görsel tasarımcıya veya OpenAPI belgesine değil, isteklere odaklanır. Koddan önce sözleşme tanımlamanız ve ekiplerle review etmeniz gerekiyorsa OpenAPI’ye özgü tasarıma öncelikli bir araç daha uygundur.

Tasarıma öncelikli çalışmak için Git dostu akıştan vazgeçmem gerekir mi?

Hayır. Git dostu çalışma yalnızca istek koleksiyonları için geçerli olmak zorunda değildir. OpenAPI belirtimi de deponuzda düz metin dosyası olarak yaşayabilir, PR içinde incelenebilir ve okunabilir farklarla yönetilebilir. Apidog’un Spec-First Modu, OpenAPI belgesini çift yönlü Git senkronizasyonuyla deponuzda tutar.

İsteğe öncelikli ve tasarıma öncelikli yaklaşımı birlikte kullanabilir miyim?

Evet. Pratikte birçok ekip önce API sözleşmesini OpenAPI ile tasarlar, ardından çalışan endpoint’leri istek istemcisiyle test eder. Önemli olan doğruluk kaynağını net tutmaktır: yeni veya paylaşılan API’lerde sözleşme merkezde olmalı, istekler bu sözleşmeyi doğrulamak için kullanılmalıdır.