Spec-First API Geliştirme Nedir?

Çoğu API hatası kodlama hatası değildir. Bunlar anlaşma hatalarıdır. Frontend `userId` beklerken, backend `user_id` gönderdi ve Kalite Güvence (QA) fark edene kadar kimse bunu fark etmedi. Şartname-öncelikli API geliştirme, sözleşmeyi belgelediğiniz son şey değil, yazdığınız ilk şey haline getirerek bu durumu düzeltir.

Bu kılavuzda, elle küçük bir OpenAPI şartnamesi yazacak, ardından herhangi bir sunucu kodu mevcut olmadan önce bu tek dosyayı kullanarak sahte (mock) veriler, testler ve belgeler oluşturacaksınız. Aynı yaklaşım birkaç farklı isimle anılır: şartname odaklı geliştirme, tasarım-öncelikli veya sözleşme-öncelikli. Hepsi aynı fikre işaret eder. Önce arayüz üzerinde anlaşın, sonra ona göre geliştirin.

Şartname-öncelikli API geliştirme nedir

Şartname-öncelikli API geliştirme, uç noktayı uygulamadan önce makine tarafından okunabilir bir sözleşme, genellikle bir OpenAPI belgesi yazmanız anlamına gelir. Bu sözleşme her yolu, parametreyi, istek gövdesini, yanıt şeklini ve durum kodunu tanımlar. Bir kez var olduğunda, API ile ilgilenen herkes için doğruluk kaynağı haline gelir.

Şartname, kodun gerisinde kalan bir belge değildir. O önderlik eder. Frontend ekipleri ondan oluşturulan bir sahte veriye karşı geliştirme yapar. QA, ona karşı testler yazar. Backend, onu karşılamak için implementasyon yapar. Her üçü de aynı dosya üzerinde anlaştığında, entegrasyon bir tahmin oyunu olmaktan çıkar.

Bu, alışılmadık bir sırayı tersine çevirir. Kod-öncelikli geliştirmede, işleyicileri yazar ve ardından genellikle elle, çoğu zaman bir sprint içinde güncelliğini yitirmiş bir şekilde tanımlarsınız. Tasarım-öncelikli bir iş akışında, açıklama önce gelir ve kod ona yanıt verir. Bu tek değişiklik, çoğu entegrasyon sorununu projenin başlangıcına, yani düzeltmenin ucuz olduğu yere taşır.

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

İki yaklaşım da aynı uç noktaları üretir. Sorunların ne zaman ortaya çıktığı ve kimlerin paralel çalışmaya başlayabileceği konusunda farklılık gösterirler.

Sağdaki sütun getiridir. Sözleşme önce var olduğunda, üç ekip birbirini engellemeyi bırakır ve tek bir paylaşılan tanıma göre inşa etmeye başlar.

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

Adım adım küçük bir /users uç noktası tasarlayalım. Her bir parça net olsun diye parçalar halinde inşa edeceğiz, sonra tam dosyayı birleştireceğiz.

Belge başlığıyla başlayalım. Bu, OpenAPI sürümünü ve temel meta verileri belirtir.

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

Ardından, components altında User şemasını tanımlayın. Bunu bir kez tanımlamak, her yerde referans vermenizi sağlar, böylece şekil istekler ve yanıtlar arasında tutarlı kalır.

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

Şimdi GET /users yolunu ekleyin. Bu, kullanıcıları listeler ve bir limit sorgu parametresini destekler. Yanıtın, User şemasını yeniden tanımlamak yerine $ref ile nasıl yeniden kullandığına dikkat edin.

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"

Bir kullanıcı oluşturmak için POST /users işlemini ekleyin. İstek gövdesi, istemcinin ne göndermesi gerektiğini tanımlar ve 201 yanıtı oluşturulan kaydı döndürür.

 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, eksiksiz ve geçerli bir sözleşmedir. Her alanı adlandırır, emaili gerekli olarak işaretler, limiti 100 ile sınırlar ve hem başarılı hem de hata yanıtlarını belirtir. Henüz kimse bir satır sunucu kodu yazmadı, ancak anlaşma kilitlendi.

Şartnameden sahte veriler, testler ve belgeler oluşturun

Şartnameyi ilk yazmanın nedeni kaldıraç etkisidir. Tek bir dosya, ekiplerin genellikle ayrı ayrı oluşturduğu üç çıktıyı yönlendirir.

Sahte Veriler (Mocks). Bir sahte sunucu, şartnamenizi okur ve her şemayla eşleşen örnek yanıtlar döndürür. format: uuid ve format: email ipuçları, araçların gerçekçi örnek veriler oluşturmasına olanak tanır. Frontend'iniz GET /users çağrısı yapar ve gerçek işleyici mevcut olmadan çok önce, ilk günden itibaren iyi biçimlendirilmiş bir kullanıcı dizisi alır. Şartname değiştiğinde, sahte veri de onunla birlikte değişir.

Testler. Şartname gerekli alanları, tipleri ve durum kodlarını bildirdiği için, bir test kahini (oracle) görevi de görür. Sözleşme testleri, POST /users için gerçek yanıtın User şemasıyla eşleşen bir gövdeyle 201 döndürdüğünü ve email eksik olduğunda 400 döndürdüğünü doğrular. Doğrulamalar icat etmiyorsunuz. Uygulamanın zaten üzerinde anlaştığınız şeyle eşleştiğini kontrol ediyorsunuz.

Belgeler. API referans belgeleri doğrudan şartnameden oluşturulur. Belgelerde gördüğünüz her uç nokta, parametre ve örnek aynı YAML'dan gelir. Senkronize tutulacak ikinci bir kopya yoktur, bu nedenle belgeler sözleşmeden sapamaz.

Bu aynı zamanda şartname-öncelikli yaklaşımın Git-tabanlı bir API iş akışıyla iyi eşleşmesini sağlar: şartname düz bir metin dosyasıdır, bu nedenle sözleşmedeki her değişiklik bir çekme isteğinde incelenebilir bir fark olarak görünür. Bir inceleyici, biri emaili yeniden adlandırdıysa veya gerekli bir alanı kaldırdıysa, yayınlanmadan önce bunu görebilir.

Apidog'da Yapmak

Apidog, bu uçtan uca desteği Şartname-Öncelikli Mod aracılığıyla sağlar. OpenAPI dosyasını bir dışa aktarım olarak ele almak yerine, dosyayı proje olarak ele alır. YAML'ı doğrudan düzenlersiniz ve çalışma alanının geri kalanı buna uyar.

/users şartnamesini düzenleyiciye yazar veya yapıştırırsınız. Apidog bunu ayrıştırır ve her iki işlem için hemen bir sahte sunucu kurar, böylece frontend'iniz onları çağırmaya başlayabilir. Oluşturulan belgeler siz yazdıkça güncellenir. Implementasyonu doğrulamaya hazır olduğunuzda, şartnamenin işlemlerini gerçek backend'inize karşı test durumları olarak çalıştırır ve yanıtların şemalarla eşleştiğini onaylarsınız.

Bunu dürüst tutan kısım iki yönlü Git senkronizasyonudur. Şartnameniz bir depoda yaşar ve değişiklikler her iki yönde akar. Düzenleyicinizde YAML'ı düzenleyip gönderdiğinizde, Apidog bunu alır. Apidog'da düzenlediğinizde ise değişiklik, ekibinizin inceleyebileceği bir commit olarak kaydedilir. Sözleşme asla aynı anda iki yerde yaşamaz. Bunun saf bir tasarım-öncelikli yaklaşımla nerede durduğuna dair daha derin bir karşılaştırma isterseniz, Apidog'da şartname-öncelikli ve tasarım-öncelikli karşılaştırmasına bakın.

Şartname-öncelikli kontrol listesi

Bir şartnameyi geliştirmeye hazır olarak adlandırmadan önce bunu kullanın:

• Şartname, OpenAPI şemasına karşı hatasız doğrulanır.
• Her uç nokta, başarı ve en az bir hata yanıtını belirtir.
• Paylaşılan şekiller components/schemas içinde bulunur ve kopyalanmak yerine $ref ile referans verilir.
• Gerekli alanlar required olarak işaretlenir ve formatlar (uuid, email, date-time) uygun yerlerde ayarlanır.
• Şartname dosyası sürüm kontrolüne kaydedilir ve çekme isteklerinde incelenir.
• Şartnameden bir sahte sunucu çalışır ve frontend ona erişebilir.
• Sözleşme testleri, gerçek yanıtları belirtilen şemalara karşı kontrol eder.
• Yayınlanan belgeler, elle tutulan bir kopya olmaksızın aynı dosyadan oluşturulur.

Her kutu işaretlenirse, ekipleriniz üç tahmin yerine tek bir anlaşmaya göre paralel olarak geliştirme yapabilir.

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 tanımlar: implementasyondan önce arayüzü yazın. "Şartname-öncelikli" en kelimesi kelimesine olan isimdir, çünkü başlangıç noktası somut bir eser olan OpenAPI şartname dosyasıdır. Pratikte terimler birbirinin yerine kullanılır.

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

Hayır. Şartnameyi görsel bir düzenleyicide oluşturup YAML'ı onun üretmesini sağlayabilir veya tercih ederseniz doğrudan YAML yazabilirsiniz. Önemli olan yazdığınız format değil, sözleşmenin koddan önce var olması ve üzerinde anlaşılmış olmasıdır. Birçok ekip ikisini birden karıştırarak, görsel olarak taslak oluşturur ve inceleme sırasında YAML'da iyileştirme yapar.

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

Şartnameyi doğruluk kaynağı yapın ve bunu uygulayın. Değişiklikler fark olarak incelenebilsin diye şartnameyi Git'te tutun. Bir yanıt şemayla eşleşmediğinde derlemenin başarısız olması için CI'da sözleşme testleri çalıştırın. İki yönlü senkronizasyon ile, her iki yerdeki düzenlemeler uzlaştırılmış kalır, bu da sapmanın en yaygın nedenini ortadan kaldırır.

Şartname-öncelikli API geliştirme, sıralamada küçük ama sonuçta büyük bir değişikliktir. Sözleşmeyi yazın, üzerinde anlaşın ve sonra ona göre geliştirin. Tüm döngüyü denemek isterseniz, Apidog'da Şartname-Öncelikli Modu açın ve deponuzu işaret edin.