TL;DR
Tasarım öncelikli yaklaşım, API spesifikasyonunuzun uygulama kodunuzdan önce yazıldığı anlamına gelir – ve spesifikasyon, 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 tutmanın sürekli zorluğunu ortadan kaldırır. Bu makale, tasarım öncelikli yaklaşımı açıklar ve Apidog'u eksiksiz bir tasarım öncelikli platform olarak kullanarak iyi araçların nasıl olması gerektiğini değerlendirir.
ApidogApidog'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. Çalışır. Ta ki çalışmayana kadar.
Dokümantasyon 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 dize döndürdüğünü söylerken, gerçek yanıt bir `value` alanı olan bir nesne dizisi döndürür.
Tasarım öncelikli yaklaşım bunu tersine çevirir. Spesifikasyon, doğruluk kaynağıdır. Kod, dokümanlar ve sahte API'ler (mocks) hepsi ondan türetilir. Spesifikasyon değiştiğinde, her şey birlikte değişir – çünkü her şey ondan türetilmiştir.
Bu teorik bir ayrım değildir. Tasarım öncelikli yaklaşımı benimseyen ekipler, daha az entegrasyon sürprizi, daha hızlı ön uç geliştirme (sahte API'ler ilk günden itibaren mevcut olduğu için) ve ikincil bir yapıt olmadığı için doğru dokümantasyon bildirmektedir.
Ancak tasarım öncelikli yaklaşım, spesifikasyonu pratik olacak kadar hızlı yazmayı sağlayan araçlar gerektirir. Spesifikasyon aracınızda bir uç nokta tanımlamak 20 dakika sürer ve rota işleyiciyi yazmak 5 dakika sürerse, kimse spesifikasyon aracını kullanmaz. Platform, tasarım öncelikli yaklaşımı kod öncelikli yaklaşımdan daha yavaş değil, daha hızlı hale getirmelidir.
Uygulamada tasarım öncelikli yaklaşım ne anlama geliyor
Tasarım öncelikli yaklaşım bir teknoloji değil, bir iş akışıdır. API geliştirmenin her aşamasında nasıl göründüğü aşağıdadır:
Hiçbir kod yazmadan önce
API tasarımı bir OpenAPI spesifikasyonu olarak tanımlanır. Bu şunları içerir:
- Tüm uç nokta yolları ve HTTP metotları
- İstek parametre tanımları (yol, sorgu, başlık)
- POST/PUT/PATCH uç noktaları için istek gövdesi şemaları
- Tüm durum kodları için yanıt şemaları (200, 400, 401, 422, 500)
- Kimlik doğrulama gereksinimleri
- Alan açıklamaları ve örnekler
Bu tasarım incelemesi, en önemli kararların alındığı yerdir: isimlendirme, veri yapıları, hata işleme desenleri.
Geliştirme sırasında
Spesifikasyon bir sahte API (mock) sunucusuna yayınlanır. Ön uç mühendisleri sahte API'ye göre geliştirme yapar. Arka uç mühendisleri, spesifikasyonu gereksinim belgesi olarak ele alarak ona göre uygulama yapar. Her iki ekip de birbirlerini engellemeden paralel çalışır.
Uygulamadan sonra
Otomatik testler, gerçek uygulamanın spesifikasyonla eşleştiğini doğrular. Sözleşmeden herhangi bir sapma testi başarısız kılar.
Gereksinimler değiştiğinde
Spesifikasyon önce güncellenir. Her iki ekip de değişikliği inceler. Sahte API'ler otomatik olarak güncellenir. Testler, güncellenmiş spesifikasyonu takip etmeyen herhangi bir uygulamayı işaretler.
Tasarım öncelikli bir platformun ihtiyaç duyduğu şeyler
Her API aracı tasarım öncelikli iş akışlarını desteklemez. İşte destekleyen araçları desteklemeyenlerden ayıran şeyler.
Görsel API düzenleyici
Ham YAML kötü bir tasarım ortamıdır. Görsel bir düzenleyici, YAML girintilemesiyle uğraşmadan API yapısına ve semantiğine odaklanmanızı sağlar. Düzenleyici geçerli OpenAPI üretmeli, şema yeniden kullanımını (bileşenler) desteklemeli ve gerçek zamanlı olarak doğrulama yapmalıdır.
OpenAPI doğrulaması
Spesifikasyon, herhangi bir şey için kullanılmadan önce geçerli OpenAPI olmalıdır. Satır içi doğrulama, hataları kod üretimi veya sahte API (mock) zamanında değil, düzenleme sırasında yakalar.
Spesifikasyondan otomatik sahte API (mock) oluşturma
Spesifikasyonu yazın, bir sahte API alın. Ek adım yok. Sahte API, şemadaki alan türlerini, formatlarını ve kısıtlamalarını dikkate alan veriler döndürmelidir. Paralel geliştirmeyi pratik hale getiren budur.
Gerçekçi örneklerle dokümantasyon önizlemesi
Spesifikasyon, tasarım aşamasında paydaşlarla paylaşabileceğiniz okunabilir dokümantasyon olarak işlenmelidir. Teknik olmayan ekip üyeleri onu okuyabilmeli ve geri bildirimde bulunabilmelidir.
Ekip inceleme iş akışı
Tasarım öncelikli yaklaşım, spesifikasyon değişikliklerini kod değişiklikleri gibi ele alır: biri bir değişiklik önerir, diğerleri inceler, onaylanır veya revize edilir. Platformun eşzamansız yorumlama ve değişiklik takibi özelliğine ihtiyacı vardır.
Standart OpenAPI'ye dışa aktarma
Spesifikasyon taşınabilir olmalıdır. Onu standart OpenAPI'ye dışa aktarabilmeli ve herhangi bir aşağı akış aracıyla kullanabilmelisiniz: kod jeneratörleri, API ağ geçitleri, test çerçeveleri.
Tasarım öncelikli bir platform olarak Apidog
Apidog'un mimarisi, spesifikasyonu birincil yapıt olarak temel alır. Tasarım sekmesi, sahte API (mock) sunucusu, test çalıştırıcısı ve dokümantasyon, hepsi aynı temel API tanımına bağlıdır.
Görsel OpenAPI düzenleyici
Apidog'un tasarım arayüzü, form tabanlı düzenlemeyi kullanır. Her uç nokta yapılandırılmış bir formdur: yol, metot, parametreler, istek gövdesi, yanıtlar. Şema alanları, bir tür seçici, açıklama düzenleyici, doğrulama kuralları ve sahte API (mock) açıklamasıyla tanımlanır.
İstemediğiniz sürece YAML yazmak zorunda değilsiniz. Apidog, spesifikasyonun YAML veya JSON temsilini gösteren ve isterseniz doğrudan düzenlemenize olanak tanıyan bir ham görünüm sunar. Görsel görünüdeki değişiklikler ham görünüme senkronize olur ve bunun tersi de geçerlidir.
Şema bileşenleri birinci sınıftır. Bileşenler bölümünde bir `UserProfile` şeması tanımlayın. Herhangi bir uç noktada `ref` ile ona başvurun. Şemayı bir kez değiştirin ve ona başvuran her uç nokta değişikliği yansıtır.
Gerçek zamanlı dokümantasyon önizlemesi
Bir uç nokta tasarlarken, dokümantasyon görünümü gerçek zamanlı olarak güncellenir. Tasarım arayüzünden ayrılmadan uç noktanın yayınlanan dokümantasyonda nasıl görüneceğini önizleyebilirsiniz. Önizleme, işlenmiş açıklamaları, alan türleri ve kısıtlamaları olan şema tablolarını ve örnek yanıtları gösterir.
İnceleme için tasarım aşamasında ürün yöneticileri veya ön uç liderleriyle bir dokümantasyon bağlantısı paylaşın. Hiçbir şey kurmaları gerekmez.
Akıllı Sahte API (Smart Mock): spesifikasyondan çalışan sahte API'ye
Apidog'un tasarımcısında yeni bir uç nokta kaydettiğinizde, sahte API (mock) sunucusu hemen hazır olur. Sahte API URL'si arayüzde görünür. Sahte API, şemalarınıza göre yanıt verileri oluşturur:
- `format: email` olan dize alanları geçerli e-posta adresleri döndürür
- `minimum` ve `maximum` değerleri olan tam sayı alanları aralıktaki değerleri döndürür
- Enum alanları rastgele seçilmiş enum değerleri döndürür
- İç içe nesneler ve diziler iç içe şema yapısını takip eder
- `$ref` bileşenleri doğru şekilde çözülür ve sahte olarak oluşturulur
Belirli senaryolar için özel sahte API (mock) kuralları da belirleyebilirsiniz: yol parametresi `0` olduğunda 404 döndürün veya belirli bir sorgu parametresi değeri için belirli bir yük döndürün.
Ekip incelemesi ve değişiklik takibi
Apidog'daki API spesifikasyon değişiklikleri tüm çalışma alanı üyeleri tarafından görülebilir. Belirli uç noktalara veya alanlara yorumlar eklenebilir. Değişiklik geçmişi, kimin neyi ne zaman değiştirdiğini takip eder.
Tasarım öncelikli iş akışları için bu, spesifikasyon değişikliklerinin ayrı bir araç veya süreç gerektirmeden kod değişiklikleriyle aynı inceleme kültüründen geçtiği anlamına gelir.
Tasarım öncelikli vs. Kod öncelikli: Gerçek ödünleşimler
Tasarım öncelikli yaklaşım evrensel olarak üstün değildir. İşte dürüst bir karşılaştırma.
Tasarım öncelikli avantajları:
- Ön uç ve arka uç paralel çalışabilir (önemli hız faydası)
- Dokümantasyon, türev değil, kaynak olduğu için doğrudur
- Entegrasyon sorunları, entegrasyon sırasında geç değil, tasarım incelemesi sırasında erken ortaya çıkar
- API sözleşmeleri açık ve doğrulanabilir
- API'deki değişiklikler varsayılan olarak bir inceleme sürecinden geçer
Tasarım öncelikli dezavantajları:
- Kod yazmadan önce spesifikasyonu tanımlamak için önceden zaman harcamak
- Spesifikasyon araçlarının öğrenme eğrisi vardır
- Uygulamayı spesifikasyonla senkronize tutmak için disiplin gerektirir
- Erken aşırı spesifikasyon, alanı anlamadan kararlara kilitlenmenize neden olabilir
Kod öncelikli avantajları:
- Küçük, deneysel projeler için daha hızlı başlangıç geliştirme
- Hızla yineleyen tek geliştiriciler için daha az süreç
- Öğrenilecek bir spesifikasyon aracı yok
Kod öncelikli dezavantajları:
- Dokümantasyon her zaman ikincil bir yapıt olup kaymaya eğilimlidir
- Ön uç, entegrasyon çalışması başlamadan önce arka ucu beklemek zorundadır
- Sözleşme örtüktür, bu da kırılma değişikliklerini tespit etmeyi zorlaştırır
- API'leri yeniden düzenlemek manuel dokümantasyon güncellemeleri gerektirir
Bir API üzerinde birden fazla mühendisin çalıştığı ekipler için, tasarım öncelikli yaklaşım genellikle daha iyi sonuçlar verir. Spesifikasyon öncelikli disiplin, önemli ön uç-arka uç koordinasyonu gerektiren özelliklerde en çok fayda sağlar.
Tasarım öncelikli iş akışlarını destekleyen araçlar
Apidog
Eksiksiz tasarım öncelikli platform: görsel düzenleyici, anında sahte API (mock) oluşturma, dokümantasyon, test ve ekip incelemesi tek bir araçta. Ücretsiz katman tüm özellik setini kapsar. Güçlü sahte API (mock) oluşturma, gerçek bir fark yaratır.
Stoplight Studio
Stil uygulaması için Spectral linting ile sınıfının en iyisi OpenAPI düzenleyici. Dahili sahte API (mock) sunucusu veya test çalıştırıcısı yok. Yönetişim araçlarına ihtiyaç duyan kuruluşlar için en iyisi. Küçük ekipler için pahalı.
SwaggerHub
Olgun OpenAPI düzenleme ve işbirliği platformu. Kurumsal alanda yaygın olarak kullanılır. Sınırlı sahte API (mock) yeteneği. Test yok. Zaten Swagger ekosisteminde olan spesifikasyon ağırlıklı kuruluşlar için iyi.
Postman (API Builder ile)
Postman'ın OpenAPI spesifikasyonları oluşturan bir API tasarım sekmesi vardır, ancak tasarım ve koleksiyon iş akışları bağlantısız hissettirir. Sahte API (mock) sunucusu, spesifikasyonlardan otomatik oluşturmak yerine koleksiyonlardan manuel kurulum gerektirir. Bazı dokümantasyon araçları isteyen kod öncelikli ekipler için çalışır.
Insomnia (belge modu ile)
Insomnia, OpenAPI spesifikasyon düzenlemeyi destekler ve temel bir sahte API (mock) sağlar. Özel tasarım öncelikli araçlara göre daha az cilalı. Hafif bir seçenek isteyen tek geliştiriciler için iyi.
Apidog'da tasarım öncelikli bir iş akışı kurma
Adım 1: Spesifikasyonla başlayın, koleksiyonla değilYeni bir proje oluşturun ve tasarım sekmesini açın. İstek oluşturucudan başlama dürtüsüne direnin. Tek bir istek göndermeden önce en azından uç nokta yolunu, metodunu ve yanıt şemasını tanımlayın.
Adım 2: Önce paylaşılan bileşenleri tanımlayınUç noktalar eklemeden önce, yeniden kullanılacak şemaları tanımlayın: hata yanıt formatı, sayfalama sarmalayıcısı, ortak varlık alanları. Bu, daha sonra tutarsızlığı önler.
Adım 3: Sahte API (mock) URL'sini erken alınUç nokta kaydedilir kaydedilmez sahte API URL'sini kopyalayın. Ön uç mühendisiyle paylaşın. Hemen ona göre geliştirmeye başlayabilirler.
Adım 4: Kod yazmadan önce dokümanları inceleyinOluşturulan dokümantasyonu önizleyin. Bir alan açıklaması dokümanlarda belirsizse, kodu okuyan herkes için belirsiz olacaktır. Spesifikasyonda düzeltin.
Adım 5: Uygulamaya başlamadan önce spesifikasyonu kilitleyinTasarım incelemesi tamamlandığında ve yorumlar çözüldüğünde, spesifikasyonu o sprint için kilitli olarak kabul edin. Spesifikasyon güncellemeleri gerektiren uygulama değişiklikleri, sessizce yapılmamalı, bir inceleme sürecinden geçmelidir.
Adım 6: CI'da şema doğrulama testlerini çalıştırınApidog'un test paketini, her CI çalıştırmasında yanıt şemalarını doğrulamak üzere ayarlayın. Bu, uygulama ve spesifikasyonu senkronize tutan otomatik koruyucu bariyerdir.
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ımlayabileceğiniz herhangi bir protokol için geçerlidir: GraphQL şema öncelikli, protobuf ile gRPC, olay tabanlı sistemler için AsyncAPI. Apidog, REST ve GraphQL tasarımını destekler. gRPC için, proto dosyaları aynı sözleşme öncelikli amaca hizmet eder.
Geliştirmeye başlamadan önce her uç noktayı tanımlamamız gerekiyor mu?Hayır. Tasarım öncelikli yaklaşımı özellik düzeyinde benimseyebilirsiniz: diğer kod tabanı bölümleri kod öncelikli olsa bile, oluşturacağınız özelliğin spesifikasyonunu kod yazmadan önce tanımlayın. Kademeli benimseme işe yarar.
Tasarım öncelikli yaklaşım çevik sprintlerle nasıl çalışır?Sprintin başlangıcındaki tasarım oturumları, o sprintin özellikleri için API sözleşmesini tanımlar. Sprint sırasında ön uç ve arka uç paralel çalışır. Spesifikasyon incelemesi sprint planlamanın bir parçası olur.
Uygulama orijinal spesifikasyondan sapmak zorunda kalırsa ne olur?Olur. Doğru süreç, önce spesifikasyonu güncellemek, paydaşlardan (özellikle ön uç) onay almak ve ardından uygulamayı güncellemektir. Bu, spesifikasyonu uygulamanın değil, doğruluk kaynağı olarak tutar.
Apidog'un OpenAPI dışa aktarımından sunucu taslakları oluşturabilir miyiz?Evet. Spesifikasyonu Apidog'dan OpenAPI 3.x olarak dışa aktarın, ardından sunucu taslakları oluşturmak için herhangi bir standart kod üreteci kullanın. openapi-generator 50'den fazla sunucu dilini ve çerçevesini destekler.
Spesifikasyon sürümlemeyi nasıl ele alıyoruz?Apidog, bir proje içinde değişiklik geçmişini tutar. Paralel olarak sürdürülen büyük sürüm değişiklikleri (hem v1 hem de v2 etkin) için ayrı projeler veya dallar iyi çalışır.
Tasarım öncelikli yaklaşım, başlangıçta küçük bir disiplin yatırımı gerektirir ve entegrasyon maliyetlerini azaltarak önemli ölçüde geri dönüş sağlar. Seçtiğiniz platform, bu başlangıç yatırımını mümkün olduğunca düşük tutmalıdır. Spesifikasyon yazmak zorsa, ekipler bunu atlayacaktır. Apidog'un görsel düzenleyicisi, anında sahte API (mock) oluşturma ve dokümantasyon önizlemesi, tasarım öncelikli yaklaşımı en erdemli yol olmaktan ziyade en az dirençli yol haline getirir.