Bruno isteğe öncelikli mi? Evet. Bruno, HTTP istekleri oluşturma, düzenleme ve gönderme etrafında inşa edilmiştir. Bir koleksiyon oluşturur, istekler eklersiniz, bunları .bru dosyalarına yazarsınız, çalıştırırsınız ve tümünü Git'te sürümlersiniz. Bu model hızlı, Git dostu ve mevcut bir API'yi keşfederken gerçek bir keyiftir.
Ancak "isteğe öncelikli" ve "tasarıma öncelikli" farklı soruları yanıtlar. İsteğe öncelikli sorar: bu uç noktayı nasıl çağırırım? Tasarıma öncelikli sorar: herhangi biri hizmet vermek için kod yazmadan önce bu uç nokta ne olmalı? Bu iki soru arasındaki boşluk, yeni veya paylaşılan API'ler geliştiren ekiplerin sürtüşme hissetmeye başladığı yerdir. Bu makale, Bruno'nun isteğe öncelikli ile tasarıma öncelikli arasındaki avantaj-dezavantaj dengesini dürüstçe ele alıyor, ardından OpenAPI'ye özgü, tasarıma öncelikli bir iş akışının nerede haklı çıktığını gösteriyor.
İsteğe öncelikliye karşı tasarıma öncelikli, kısaca
İki yaklaşım rakip olmaktan ziyade farklı başlangıç noktalarıdır. İşte kısa özeti.
| Boyut | İsteğe Öncelikli (Bruno) | Tasarıma Öncelikli (OpenAPI'ye özgü) |
|---|---|---|
| Başlangıç Oluşumu | Gönderebileceğiniz bir istek | Bir sözleşme (OpenAPI belirtimi) |
| En iyisi | Mevcut API'leri keşfetmek ve test etmek | Koddan önce yeni/paylaşılan API'ler tasarlamak |
| Doğruluk kaynağı | İstek koleksiyonu | Belirtim |
| Ekipler arası inceleme | Uç noktalar oluştuktan sonra | Bir satır 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) |
Araç belirtimi Git ile senkronize ettiğinde güçlü |
Her iki sütun da "yanlış" değildir. Doğru seçim, API'nizin zaten var olup olmamasına veya şu anda onu tanımlayıp tanımlamadığınıza bağlıdır.
Bruno'nun isteğe öncelikli modeli
Bruno işini iyi yapıyor ve bu işin ne olduğu konusunda kesin olmakta fayda var. İstekleri, sahip olduğunuz bir klasörde düz metin .bru dosyaları olarak saklar. Zorunlu bir bulut hesabı, tescilli bir senkronizasyon, devre dışı bırakmanız gereken bir arka plan telemetrisi yoktur. API istemcisinin kod tabanlarının geri kalanı gibi davranmasını isteyen geliştiriciler için bu gerçek bir avantajdır ve birçok ekibin benimsediği Git'e özgü API iş akışının çekirdeğidir.
Bruno'nun öne çıktığı yerler:
- Mevcut bir API'yi keşfetme. Çalışan bir hizmete yönlendirin, istekler gönderin, yanıtları inceleyin, yineleyin. Geri bildirim döngüsü sıkıdır.
- Önce yerel ve Git dostu. Farklar okunabilir, birleştirmeler mantıklıdır ve istek geçmişiniz kodunuzla aynı PR'da yaşar.
- Betikleme ve test etme. İstek öncesi ve sonrası betikler, onaylamalar ve ortam değişkenleri, çoğu mühendisin ihtiyaç duyduğu günlük testleri kapsar.
- Kilitlenme yok. Biçim açık ve dosyalar sizin.
İşiniz mevcut API'leri tüketmek ve doğrulamaksa, isteğe öncelikli genellikle en doğrudan yoldur. Bu Bruno alternatif değerlendirmesinde onu daha geniş platformlarla karşılaştırırken de aynı şeyi söylemiştik.
Tasarım veya sözleşme katmanının olmamasının maliyeti
Avantaj-dezavantaj dengesi, API'nin henüz mevcut olmadığı veya birden fazla ekibin nasıl görünmesi gerektiği konusunda anlaşması gerektiği anda ortaya çıkar.
Görsel tasarımcı yok. İsteğe öncelikli araçlar, uç noktaları kaynakların, şemaların ve yanıtların bir modeli olarak değil, istekler olarak ifade eder. Bir ürün mühendisinin, bir arka uç liderinin ve bir ön uç geliştiricisinin aynı kaynak şekline bakıp, herhangi biri bir işleyici yazmadan önce üzerinde anlaşabileceği bir tuval yoktur. İsteklerde tasarım yapmak, örneklerle tasarım yapmak anlamına gelir ve örnekler yapıyı zorlamaz.
Sözleşme sapması. Koleksiyon doğruluk kaynağı olduğunda, yalnızca birinin zaten çağırdığı şeyleri yansıtır. Gerçek API değişebilir, bir alan ekleyebilir, bir parametreyi kullanımdan kaldırabilir, doğrulamayı sıkılaştırabilir ve bir test başarısız olana kadar koleksiyon sessizce geride kalır. Belirtim merkezli bir iş akışı bunu tersine çevirir: sözleşme referanstır ve uygulama buna göre kontrol edilir.
Koddan önce daha zor ekipler arası inceleme. Bir istek klasörünü incelemek size uç noktaların bugün nasıl çağrıldığını söyler. Bir inceleyiciye, uygulamadan önce onaylayacağı temiz, bildirime dayalı bir belge sunmaz. API değişikliklerini tasarım incelemesi yoluyla kontrol eden ekipler için, birinci sınıf bir sözleşmenin olmaması bu incelemeyi daha yavaş ve daha özel hale getirir.
Bunların hiçbiri Bruno'yu kötü bir araç yapmaz. Bu, Bruno'yu istek öncelikli olduğu işin dışında kullanılan, isteğe öncelikli bir araç yapar.
Tasarıma öncelikli ne zaman kazanır
Tasarıma öncelikli özellikle üç durumda karşılığını verir:
- Greenfield API'ler. Henüz hiçbir şey mevcut olmadığında, belirtim tasarımın kendisidir. Kaynakları, şemaları ve hata şekillerini bir kez tanımlar, ardından daha sonra isteklerden tersine mühendislikle çıkarmak yerine, bu tek sözleşmeden sunucu taslakları, maketler ve belgeler oluşturursunuz.
- Çok ekipli sözleşmeler. Bir arka uç ekibi ve bir veya daha fazla istemci ekibinin anlaşması gerektiğinde, OpenAPI belirtimi anlaşmadır. Ön uç, gerçek uç noktaları beklemek yerine, sözleşme onaylandığı anda bir makete karşı paralel olarak arka uç uygulamasıyla birlikte geliştirmeye başlayabilir.
- Herkese açık API'ler. Harici geliştiriciler size bağımlı olduğunda, istikrar ve net dokümantasyon üründür. Bakımlı bir sözleşme size oluşturulmuş referans belgeleri, sürümleme disiplini ve kasıtlı olarak kırılan değişiklikleri iletmenin bir yolunu sunar.
Ortak nokta: API, koddan _önce_ anlaşmaya ihtiyaç duyan paylaşılan bir arayüz olduğunda tasarıma öncelikli kazanır, sadece gönderildikten _sonra_ kurcaladığınız bir hizmet değil.
Apidog tasarıma öncelikli artı Spec-First Modu
Apidog tasarıma öncelikli olarak geliştirilmiştir ve buradaki ilgili nokta, bunu elde etmek için OpenAPI'ye özgü, Git dostu deneyimden vazgeçmek zorunda kalmamanızdır.
Aynı proje üzerinde iki şekilde çalışabilirsiniz. Uç noktaları, istek ve yanıt şemalarını ve yeniden kullanılabilir bileşenleri YAML'yi elle yazmadan tanımlamak için görsel tasarımcı; çoğu insanın "tasarıma öncelikli" denince hayal ettiği budur. Ve belirtimin gerçek doğruluk kaynağı olduğu, OpenAPI belgesini doğrudan yazdığınız bir kod düzenleyicisi olan Spec-First Modu var. İkisi senkronize kalır, böylece bir arka uç mühendisi ham OpenAPI'de çalışırken bir ürün mühendisi tuval üzerinde çalışabilir ve aynı sözleşmeyi düzenliyor olurlar.
Spec-First Modu aynı zamanda çift yönlü Git senkronizasyonunu da destekler: belirtim deponuzda gerçek bir dosya olarak yaşar, değişiklikler her iki yönde de akar ve API tasarımınız kodunuzla aynı çekme istekleri ve incelemeden geçer. Bruno kullanıcılarının değer verdiği Git'e özgü özellik, istek koleksiyonuna değil, _sözleşmeye_ uygulanmıştır. Tüm mekanikler Spec-First Modu dokümantasyonunda yer almaktadır.
Sonuç olarak, her iki soruyu da kapsayan tek bir iş akışı elde edilir: gerektiğinde önce sözleşmeyi tasarlayın ve uç noktalar yayında olduğunda bile onu isteğe öncelikli bir istemci gibi test edin. Bu modellerin nerede buluştuğuna daha yakından bakmak için Apidog'da belirtim öncelikliye karşı tasarım öncelikli makalesine bakın.
Ekip olgunluğuna göre seçim
Karar vermenin basit bir yolu: aracı API'nizin yaşam döngüsündeki yerine göre eşleştirin, bir tercihe göre değil.
- Yalnız veya küçük ekip, çoğunlukla API'leri tüketen. İsteğe öncelikli yeterlidir. Bruno'nun önce yerel modeli sizi yormaz ve ihtiyacınız olmayan resmi bir sözleşmeyi sürdürme yükünü taşımazsınız.
- Kendi API'lerini yayınlayan büyüyen ekip. Bu, dönüm noktasıdır. İkinci bir ekip uç noktalarınıza bağımlı olduğunda, gayri resmi bir koleksiyon ölçeklenmeyi durdurur ve açık bir sözleşme size inceleme döngüleri ve entegrasyon hatalarından tasarruf etmeye başlar.
- Herkese açık veya birçok dahili API'ye sahip olgun kuruluş. Tasarıma öncelikli fiilen gereklidir. Belirtim, yönetişim, dokümantasyon ve yeni kullanıcıları sisteme dahil etme süreçlerinin hepsini bir kerede sağlar ve Git senkronizasyonuna sahip OpenAPI'ye özgü bir araç bunu dürüst tutar.
Bruno'nun isteğe öncelikli ve tasarıma öncelikli arasındaki dürüst yorum, genellikle zevkin değil, olgunluğun karar verdiğidir. Ekipler genellikle isteğe öncelikli olarak başlar ve API'leri başkalarının güvendiği sözleşmeler haline geldikçe tasarıma öncelikliye doğru ilerler.
Sıkça Sorulan Sorular
Bruno isteğe öncelikli mi yoksa tasarıma öncelikli mi?
Bruno isteğe önceliklidir. Çekirdek modeli, mevcut API'leri keşfetmek ve test etmek için ideal olan düz metin dosyaları olarak depolanan istekleri oluşturmak, düzenlemek ve göndermektir. API oluşturulmadan önce bir OpenAPI sözleşmesi yazmaya odaklanmaz.
Bruno'da tasarıma öncelikli çalışma yapabilir miyim?
Belirtim merkezli bir aracın yaptığı şekilde doğal olarak değil. Bruno, doğruluk kaynağı olarak görsel bir tasarımcıya veya bir OpenAPI belgesine odaklanmak yerine isteklere odaklanır. Koddan önce bir sözleşmeyi tanımlamanız ve incelemeniz gerekiyorsa, tasarıma öncelikli, OpenAPI'ye özgü bir araç bu işe daha iyi uyar.
Tasarıma öncelikli olmak için Git dostluğunu bırakmak zorunda mıyım?
Hayır. Git'e özgü özellik, deponuzdaki düz metin dosyaları, okunabilir farklar, PR'lar aracılığıyla inceleme, belirtimin kendisine uygulanabilir. Apidog'un Spec-First Modu, OpenAPI belgesini çift yönlü senkronizasyonla deponuzda tutar, bu nedenle tasarıma öncelikli olmak Git'i geride bırakmak anlamına gelmez.