Tobias Hoffmann

Posted on Apr 30 • Originally published at apidog.com

Tasarım Odaklı API İş Akışı için API Platformu

TL;DR

Tasarım öncelikli yaklaşımda API spesifikasyonu uygulama kodundan önce yazılır ve sonraki her şeyi yönlendirir: sahte API'ler (mocks), dokümantasyon, testler ve istemci taslakları. Bu iş akışını baştan sona destekleyen bir platform seçmek, kod ve dokümanları senkronize tutma yükünü azaltır. Bu makale, tasarım öncelikli yaklaşımı pratik bir iş akışı olarak açıklar ve Apidog'u eksiksiz bir tasarım öncelikli platform örneği olarak değerlendirir.

Apidog'u bugün deneyin

Apidog

Apidog'u ücretsiz deneyin

Giriş

Çoğu geliştirici API'leri önce kod yazarak geliştirmeyi öğrenir. Bir rota yazarsınız, bazı açıklamalar eklersiniz, bir jeneratör çalıştırırsınız ve dokümantasyon elde edersiniz. Bu yaklaşım bir noktaya kadar çalışır.

Sorun genellikle bakım aşamasında başlar:

Dokümantasyon gerçek davranıştan sapar.
Açıklamalar güncelliğini yitirir.
Yeni bir mühendis yanıt formatını değiştirir ancak dekoratörü güncellemeyi unutur.
Altı ay sonra dokümantasyon API'nin bir dizi string döndürdüğünü söylerken, gerçek yanıt value alanı olan nesnelerden oluşur.

Tasarım öncelikli yaklaşım bu akışı tersine çevirir. Spesifikasyon doğruluk kaynağıdır. Kod, dokümantasyon, mock sunucusu ve testler bu sözleşmeden türetilir.

Bu sadece süreç tercihi değildir. Tasarım öncelikli çalışan ekipler genellikle şu avantajları elde eder:

Daha az entegrasyon sürprizi
İlk günden kullanılabilir mock API ile daha hızlı ön uç geliştirme
İkincil bir çıktı olmadığı için daha doğru dokümantasyon
Daha net API sözleşmeleri

Ancak bu yaklaşımın çalışması için spesifikasyon yazmak pratik olmalıdır. Bir uç nokta tanımlamak 20 dakika, rota işleyicisini yazmak 5 dakika sürüyorsa ekip spesifikasyonu atlar. Araç, tasarım öncelikli yaklaşımı kod öncelikli yaklaşımdan daha yavaş değil, daha akıcı hale getirmelidir.

Uygulamada tasarım öncelikli yaklaşım ne anlama geliyor?

Tasarım öncelikli yaklaşım bir teknoloji değil, bir API geliştirme iş akışıdır.

1. Kod yazmadan önce sözleşmeyi tanımlayın

API tasarımı önce OpenAPI spesifikasyonu olarak tanımlanır. Minimum olarak şunları içermelidir:

Uç nokta yolları ve HTTP metotları
Path, query ve header parametreleri
POST, PUT, PATCH için request body şemaları
200, 400, 401, 422, 500 gibi yanıt şemaları
Kimlik doğrulama gereksinimleri
Alan açıklamaları ve örnekler

Örnek basit bir OpenAPI parçası:

paths:
  /users/{id}:
    get:
      summary: Kullanıcı profilini getir
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "Başarılı yanıt"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserProfile"
        "404":
          description: "Kullanıcı bulunamadı"

Bu aşamada en önemli kararlar verilir:

İsimlendirme
Veri yapıları
Hata formatları
Sayfalama modeli
Kimlik doğrulama davranışı

2. Geliştirme sırasında mock API kullanın

Spesifikasyon mock sunucusuna yayınlanır. Böylece:

Ön uç mühendisleri gerçek backend hazır olmadan geliştirme yapabilir.
Backend mühendisleri spesifikasyonu gereksinim belgesi olarak kullanır.
Ekipler birbirini beklemeden paralel ilerler.

Ön uç tarafında örnek kullanım:

const response = await fetch("https://mock.example.com/users/123");
const user = await response.json();

console.log(user.email);

Backend henüz yazılmamış olsa bile UI geliştirme, validasyon ve entegrasyon hazırlığı başlayabilir.

3. Uygulamadan sonra sözleşme testi çalıştırın

Gerçek API tamamlandığında testler uygulamanın spesifikasyonla eşleştiğini doğrulamalıdır.

Örnek kontrol mantığı:

GET /users/{id}
Beklenen response schema: UserProfile
Gerçek response schema ile karşılaştır
Sapma varsa testi başarısız yap

Bu, dokümantasyon ve gerçek API arasındaki farkları erken yakalar.

4. Gereksinim değiştiğinde önce spesifikasyonu güncelleyin

Bir alan ekleniyorsa, kaldırılıyorsa veya yanıt formatı değişiyorsa önce OpenAPI sözleşmesi güncellenmelidir.

Doğru akış:

Spesifikasyonu güncelleyin.
Ön uç ve backend ekipleri değişikliği incelesin.
Mock API güncellensin.
Uygulama değiştirilsin.
Testler yeni sözleşmeye göre çalışsın.

Tasarım öncelikli bir platformda olması gerekenler

Her API aracı tasarım öncelikli iş akışını iyi desteklemez. Aşağıdaki özellikler kritik önemdedir.

Görsel API düzenleyici

Ham YAML ile çalışmak her zaman verimli değildir. Görsel bir düzenleyici:

Path, method, parametre ve response tanımlarını form üzerinden oluşturmalıdır.
Geçerli OpenAPI üretmelidir.
Şema bileşenlerini yeniden kullanmayı desteklemelidir.
Hataları düzenleme sırasında göstermelidir.

OpenAPI doğrulaması

Spesifikasyon mock, dokümantasyon veya kod üretimi için kullanılmadan önce geçerli OpenAPI olmalıdır.

İyi bir araç şu hataları erken yakalamalıdır:

Eksik response açıklaması
Geçersiz schema tipi
Yanlış $ref
Eksik required alanları
Hatalı security tanımı

Spesifikasyondan otomatik mock API oluşturma

İdeal akış şu kadar kısa olmalıdır:

OpenAPI endpoint tanımla
→ Kaydet
→ Mock URL hazır

Mock sunucusu şemadaki alan türlerini ve kısıtlamaları dikkate almalıdır:

format: email
minimum / maximum
enum
nested object
array
$ref bileşenleri

Dokümantasyon önizlemesi

Spesifikasyon sadece makine tarafından okunabilir olmamalıdır. Ekip içi inceleme için okunabilir dokümantasyona dönüşmelidir.

Dokümantasyon önizlemesi şunları göstermelidir:

Endpoint açıklaması
Request parametreleri
Request body
Response schema
Örnek response
Hata durumları

Ekip inceleme iş akışı

API sözleşmesi kod kadar önemlidir. Bu nedenle değişiklikler de kod değişiklikleri gibi incelenmelidir.

Gerekli özellikler:

Yorum ekleme
Değişiklik geçmişi
Kim, neyi, ne zaman değiştirdi bilgisinin tutulması
Endpoint veya alan bazında tartışma

Standart OpenAPI dışa aktarımı

Spesifikasyon taşınabilir olmalıdır. Platformdan standart OpenAPI olarak dışa aktarılıp şu araçlarla kullanılabilmelidir:

Kod jeneratörleri
API gateway'ler
Test framework'leri
Dokümantasyon araçları
CI doğrulama adımları

Tasarım öncelikli bir platform olarak Apidog

Apidog'un mimarisi spesifikasyonu birincil çıktı olarak ele alır. Tasarım sekmesi, mock sunucusu, test çalıştırıcısı ve dokümantasyon aynı API tanımına bağlıdır.

Görsel OpenAPI düzenleyici

Apidog'un tasarım arayüzü form tabanlıdır. Her endpoint yapılandırılmış bir şekilde tanımlanır:

Path
HTTP method
Parametreler
Request body
Response'lar
Schema alanları
Açıklamalar
Validasyon kuralları
Mock açıklamaları

YAML yazmak zorunda değilsiniz. Ancak isterseniz ham YAML veya JSON görünümünü açıp doğrudan düzenleyebilirsiniz. Görsel görünümdeki değişiklikler ham görünüme, ham görünümdeki değişiklikler de görsel görünüme senkronize olur.

Şema bileşenlerini tekrar kullanın

Ortak modelleri bileşen olarak tanımlayın.

Örnek:

components:
  schemas:
    UserProfile:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: string
          example: usr_123
        email:
          type: string
          format: email
          example: user@example.com
        displayName:
          type: string
          example: Ayşe Yılmaz

Daha sonra herhangi bir endpoint içinde bu şemaya referans verebilirsiniz:

schema:
  $ref: "#/components/schemas/UserProfile"

Bu yaklaşım tutarlılığı artırır. UserProfile değiştiğinde onu kullanan endpoint'ler aynı sözleşmeyi takip eder.

Gerçek zamanlı dokümantasyon önizlemesi

Bir endpoint tasarlarken dokümantasyon görünümü gerçek zamanlı olarak güncellenir. Böylece tasarım arayüzünden çıkmadan yayınlanacak dokümantasyonun nasıl görüneceğini kontrol edebilirsiniz.

Bu özellikle inceleme aşamasında faydalıdır:

Endpoint'i tanımlayın.
Dokümantasyon önizlemesini açın.
Alan açıklamalarını kontrol edin.
Ürün yöneticisi veya ön uç lideriyle bağlantıyı paylaşın.
Geri bildirimi spesifikasyon üzerinde uygulayın.

Eğer bir alan açıklaması dokümantasyonda belirsiz görünüyorsa, uygulama sırasında da belirsizlik yaratacaktır.

Akıllı Mock: spesifikasyondan çalışan mock API'ye

Apidog'da yeni bir endpoint kaydedildiğinde mock sunucusu hemen kullanılabilir hale gelir. Mock URL arayüzde görünür.

Mock yanıtları şemalara göre oluşturulur:

format: email olan string alanları geçerli e-posta adresleri döndürür.
minimum ve maximum değerleri olan integer alanları belirtilen aralıkta değerler döndürür.
Enum alanları tanımlı değerlerden birini döndürür.
İç içe nesneler ve diziler schema yapısını takip eder.
$ref bileşenleri çözülür ve mock response içinde kullanılır.

Belirli senaryolar için özel mock kuralları da tanımlayabilirsiniz:

Path parametresi 0 olduğunda 404 döndür.
Belirli bir query parametresi için özel payload döndür.
Hata yanıtlarını ön uç validasyonu için test et.

Örnek senaryo:

GET /users/0 → 404 Not Found
GET /users/123 → 200 UserProfile

Bu, UI tarafında başarı ve hata durumlarını backend beklemeden test etmeyi sağlar.

Ekip incelemesi ve değişiklik takibi

Apidog'daki API spesifikasyon değişiklikleri çalışma alanı üyeleri tarafından görülebilir. Belirli endpoint'lere veya alanlara yorum eklenebilir. Değişiklik geçmişi kimin neyi ne zaman değiştirdiğini takip eder.

Tasarım öncelikli iş akışında bu önemlidir çünkü API sözleşmesi artık ayrı bir dosya değil, ekip tarafından incelenen ve sürdürülen merkezi bir kaynaktır.

Tasarım öncelikli vs. kod öncelikli: gerçek ödünleşimler

Tasarım öncelikli yaklaşım her durumda otomatik olarak en iyi seçenek değildir. Karar verirken aşağıdaki farkları dikkate alın.

Tasarım öncelikli avantajları

Ön uç ve backend paralel çalışabilir.
Dokümantasyon türev değil, kaynak olduğu için daha doğru kalır.
Entegrasyon sorunları geç aşamada değil, tasarım incelemesinde ortaya çıkar.
API sözleşmeleri açık ve doğrulanabilir olur.
API değişiklikleri varsayılan olarak inceleme sürecinden geçer.

Tasarım öncelikli dezavantajları

Kod yazmadan önce spesifikasyon için zaman ayırmak gerekir.
Spesifikasyon araçlarının öğrenme eğrisi vardır.
Uygulama ve spesifikasyonu senkronize tutmak disiplin ister.
Alan tam anlaşılmadan aşırı detaylı spesifikasyon yazmak kararları erken kilitleyebilir.

Kod öncelikli avantajları

Küçük ve deneysel projelerde başlangıç daha hızlı olabilir.
Tek geliştiricili hızlı prototiplerde daha az süreç gerektirir.
Ek bir spesifikasyon aracı öğrenmek gerekmez.

Kod öncelikli dezavantajları

Dokümantasyon ikincil çıktıdır ve sapmaya açıktır.
Ön uç genellikle backend'in hazır olmasını bekler.
Sözleşme örtüktür; kırılma değişikliklerini yakalamak zordur.
API refactor işlemleri manuel dokümantasyon güncellemeleri gerektirir.

Bir API üzerinde birden fazla mühendis çalışıyorsa tasarım öncelikli yaklaşım genellikle daha iyi sonuç verir. En fazla fayda, ön uç ve backend koordinasyonu yüksek olan özelliklerde görülür.

Tasarım öncelikli iş akışlarını destekleyen araçlar

Apidog

Eksiksiz tasarım öncelikli platform: görsel düzenleyici, anında mock API oluşturma, dokümantasyon, test ve ekip incelemesi tek araçta bulunur. Ücretsiz katman tüm özellik setini kapsar. Güçlü mock oluşturma yeteneği pratik iş akışlarında belirgin fark yaratır.

Stoplight Studio

Spectral linting ile güçlü bir OpenAPI düzenleyicidir. Stil kuralları ve API yönetişimi için uygundur. Dahili mock sunucusu veya test çalıştırıcısı yoktur. Yönetişim araçlarına ihtiyaç duyan kuruluşlar için daha uygundur.

SwaggerHub

Olgun bir OpenAPI düzenleme ve işbirliği platformudur. Kurumsal alanda yaygın kullanılır. Mock yetenekleri sınırlıdır ve test odaklı değildir. Swagger ekosisteminde olan spesifikasyon ağırlıklı ekipler için uygundur.

Postman API Builder

Postman'ın OpenAPI spesifikasyonları oluşturabilen API tasarım özellikleri vardır. Ancak tasarım ve koleksiyon iş akışları ayrı hissedebilir. Mock sunucusu genellikle spesifikasyondan otomatik türetmek yerine koleksiyonlar üzerinden yapılandırılır. Kod öncelikli başlayıp dokümantasyon eklemek isteyen ekipler için çalışabilir.

Insomnia Belge Modu

Insomnia, OpenAPI spesifikasyon düzenlemeyi destekler ve temel mock özellikleri sunar. Özel tasarım öncelikli platformlara göre daha hafiftir. Tek geliştiriciler veya küçük projeler için uygun olabilir.

Apidog'da tasarım öncelikli bir iş akışı kurma

Adım 1: Koleksiyonla değil, spesifikasyonla başlayın

Yeni bir proje oluşturun ve tasarım sekmesini açın. İlk iş olarak istek göndericiye geçmeyin.

Önce en azından şunları tanımlayın:

Endpoint path
HTTP method
Başarılı response schema
Temel hata response'ları

Örnek başlangıç checklist'i:

[ ] GET /users/{id}
[ ] Path param: id
[ ] 200 response: UserProfile
[ ] 404 response: ErrorResponse
[ ] Auth gereksinimi

Adım 2: Önce paylaşılan bileşenleri oluşturun

Endpoint eklemeden önce ortak şemaları tanımlayın:

Hata yanıtı
Sayfalama sarmalayıcısı
Ortak entity alanları
Kimlik doğrulama hataları

Örnek hata formatı:

components:
  schemas:
    ErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          example: USER_NOT_FOUND
        message:
          type: string
          example: Kullanıcı bulunamadı

Bu, her endpoint'in farklı hata formatı üretmesini önler.

Adım 3: Mock URL'yi erken paylaşın

Endpoint kaydedilir kaydedilmez mock URL'yi kopyalayın ve ön uç geliştiriciyle paylaşın.

Ön uç ekibi şu işleri hemen yapabilir:

UI entegrasyonu
Loading state
Empty state
Error state
Form validasyonu
Response mapping

Backend henüz tamamlanmamış olsa bile geliştirme başlayabilir.

Adım 4: Kod yazmadan önce dokümantasyonu inceleyin

Oluşturulan dokümantasyon önizlemesini kontrol edin.

Şu soruları sorun:

Alan adları açık mı?
Hata durumları yeterince tanımlı mı?
Response örneği gerçekçi mi?
Ön uç geliştirici bu dokümana bakarak entegrasyon yapabilir mi?
Auth gereksinimi net mi?

Belirsizlik varsa kodda değil, spesifikasyonda düzeltin.

Adım 5: Uygulamaya başlamadan önce sözleşmeyi kilitleyin

Tasarım incelemesi tamamlandığında ve yorumlar çözüldüğünde spesifikasyonu o sprint için kilitli kabul edin.

Uygulama sırasında sözleşme değişikliği gerekiyorsa sessizce kodu değiştirmeyin. Doğru akış:

Spec değişikliği öner
→ Ekip incelemesi
→ Mock güncellemesi
→ Uygulama değişikliği
→ Test doğrulaması

Adım 6: CI'da schema doğrulama testleri çalıştırın

Apidog test paketini her CI çalıştırmasında response schema doğrulaması yapacak şekilde ayarlayın.

Amaç:

Gerçek API, OpenAPI sözleşmesine uyuyor mu?
Beklenen alanlar var mı?
Alan tipleri doğru mu?
Hata response'ları dokümantasyonla eşleşiyor mu?

Bu adım uygulama ve spesifikasyonu senkronize tutan otomatik koruyucu katmandır.

Sıkça Sorulan Sorular

Tasarım öncelikli yaklaşım sadece REST API'ler için mi geçerli?

Hayır. Tasarım öncelikli prensip, sözleşme tanımlayabildiğiniz herhangi bir protokol için geçerlidir:

REST için OpenAPI
GraphQL için schema-first yaklaşım
gRPC için protobuf
Olay tabanlı sistemler için AsyncAPI

Apidog REST ve GraphQL tasarımını destekler. gRPC tarafında proto dosyaları benzer sözleşme öncelikli amacı taşır.

Geliştirmeye başlamadan önce her endpoint'i tanımlamak zorunda mıyız?

Hayır. Tasarım öncelikli yaklaşımı özellik bazında benimseyebilirsiniz.

Örneğin mevcut kod tabanı kod öncelikli olabilir, ancak yeni geliştireceğiniz ödeme özelliği için önce spesifikasyon yazabilirsiniz. Kademeli benimseme pratik ve uygulanabilir bir yaklaşımdır.

Tasarım öncelikli yaklaşım çevik sprintlerle nasıl çalışır?

Sprint başındaki tasarım oturumlarında o sprint'in API sözleşmeleri tanımlanır. Sprint sırasında ön uç ve backend paralel çalışır.

Tipik akış:

Sprint planlama
→ API sözleşmesi
→ Mock paylaşımı
→ Paralel frontend/backend geliştirme
→ Schema doğrulama
→ Entegrasyon

Spesifikasyon incelemesi sprint planlamanın doğal bir parçası olur.

Uygulama orijinal spesifikasyondan sapmak zorunda kalırsa ne olur?

Bu olabilir. Doğru süreç uygulamayı sessizce değiştirmek değildir.

Önce spesifikasyonu güncelleyin, paydaşlardan özellikle ön uç ekibinden onay alın, ardından uygulamayı değiştirin. Böylece spesifikasyon doğruluk kaynağı olarak kalır.

Apidog'un OpenAPI dışa aktarımından sunucu taslakları oluşturabilir miyiz?

Evet. Spesifikasyonu Apidog'dan OpenAPI 3.x olarak dışa aktarabilir ve standart kod üreteçleriyle kullanabilirsiniz. Örneğin openapi-generator, 50'den fazla sunucu dili ve framework'ü destekler.

Örnek komut:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g nodejs-express-server \
  -o ./generated-server

Spesifikasyon sürümlemeyi nasıl ele alıyoruz?

Apidog proje içinde değişiklik geçmişini tutar. Paralel sürdürülen büyük sürüm değişiklikleri için ayrı projeler veya dallar kullanılabilir.

Örnek yaklaşım:

api-v1 → mevcut üretim sözleşmesi
api-v2 → yeni major değişiklikler

Sonuç

Tasarım öncelikli yaklaşım başlangıçta küçük bir disiplin yatırımı ister, ancak entegrasyon maliyetlerini azaltarak güçlü bir geri dönüş sağlar.

Başarılı olmak için kritik nokta aracın bu süreci kolaylaştırmasıdır. Spesifikasyon yazmak zorsa ekipler bunu atlar. Görsel düzenleyici, anında mock API, dokümantasyon önizlemesi, test ve ekip incelemesi aynı akışta olduğunda tasarım öncelikli yaklaşım teorik bir ideal olmaktan çıkar ve günlük geliştirme sürecinin doğal parçası haline gelir.