Bruno API Koleksiyonlarını Git'te Tutmak: Bedava Postman Değil, Bir İş Akışı Değişikliği

API koleksiyonunuz bir bulut sağlayıcıda ya da tek bir mühendisin laptopunda yaşarken, o uç noktalara hizmet veren kod git’te yaşıyor. Bir uç nokta zorunlu bir header eklediği veya bir alanı yeniden adlandırdığı anda ikisi birbirinden uzaklaşır: kod değişikliği bir pull request ile gider, ama kaydedilmiş istek geride kalır ve koleksiyonu sonradan açan kişi, artık gerçeğe uymayan bir isteği debug eder. Çözüm, istek koleksiyonunuzu kodun yanında düz metin dosyaları olarak commit etmektir; böylece API sözleşmesi, kullandığı handler ile aynı pull request, aynı inceleme ve aynı geçmişten geçer. Buradaki araç Bruno, ama asıl mesele onu hangi istemcinin gösterdiğinden çok sözleşmenin nerede yaşadığı; secret’lar etrafında net bir sınır ve bulut iş birliğinin hâlâ kazandığı birkaç durum var.

En baştan söylemekte fayda var: bir istemciyi, denk geldiği için bedava olan bir başkasıyla değiştirmek yalnızca araç faturanızı değiştirir; iş akışınız olduğu gibi kalır. İş akışını değiştiren şey koleksiyonu commit etmektir, çünkü bu, drift’in saklandığı ikinci sistemi ortadan kaldırır.

API Değişikliği PR İçinde İncelenir

Bruno her isteği, repo’ya commit ettiğiniz bir koleksiyon klasörü içinde düz metin dosyası olarak saklar. Format “Bru” adında, düz metin dosyaları üzerine kurulu basit bir işaretleme dilidir; JSON yerine küçük bir DSL’dir ve diff’lerin bir pull request içinde temiz okunmasını sağlayan da budur. Asgari bir istek şöyle görünür:

meta {
  name: Get user
  type: http
  seq: 1
}

get {
  url: {{baseUrl}}/users/42
  body: none
  auth: bearer
}

headers {
  Accept: application/json
}

auth:bearer {
  token: {{authToken}}
}

assert {
  res.status: eq 200
  res.body.id: eq 42
}

/users/42 uç noktası yeni bir Accept değeri istemeye başladığında ya da yanıt, bir assertion’ın kontrol etmesi gereken bir alan kazandığında, bu dosyayı handler ile aynı commit içinde düzenlersiniz. İnceleyen kişi her iki diff’i yan yana görür: bir tarafta handler değişikliği, diğer tarafta istek değişikliği. Sözleşme değişikliği, kodu inceleyen aynı kişi tarafından, metin olarak, akışın içinde incelenir.

Bunu bulut tabanlı bir koleksiyonla kıyaslayın. Handler düzenlemesi git’te, istek düzenlemesi sağlayıcının uygulamasında yaşar. Bu iki sistem ve iki zaman çizelgesidir; drift etmeleri için kaza gerekmez, varsayılan davranış budur. Bruno’nun kendi anlatımı da bununla birebir örtüşür: kendisini “Git-native API istemcisi” olarak, “kod olarak saklanan koleksiyonlar” ile konumlandırır ve “Yalnızca Yerel” olduğunu, bulut senkronizasyonu olmadığını açıkça söyler; yani veriniz repo’da kalır. İş birliği pull request’ler üzerinden olur, çünkü insan tarafından okunabilen dosya formatı değişikliği okunabilir kılar.

Araç hızla evrildiği için formatla ilgili bir not. Bruno .bru’yu hâlâ tam olarak destekliyor, ama yeni koleksiyonlar için artık kendi yazdığı açık bir spesifikasyon olan OpenCollection YAML’ı öneriyor. Argüman dosya uzantısına bağlı değil. Her iki format da düz metindir, ikisi de repo’da yaşar ve ikisi de bir pull request üzerinden incelenir. Mevcut koleksiyonlarınız .bru kullanıyorsa onunla devam edin; sıfırdan bir koleksiyonda OpenCollection YAML’a uzanın. İş akışı değişikliği her iki durumda da aynıdır.

Secret Sınırı

“Her şeyi commit et” cümlesinin içine gömülü tuzak şu: aslında her şeyi commit etmezsiniz. İsteğin şekli git’e girer; secret değerler girmez. Bruno’nun dokümanları bu konuda açıktır: koleksiyonu git’e ister check-in edin ister export edin, “paylaşılmadan önce secret’ların koleksiyondan ayıklandığından emin olmak isteriz” der. Bu sınırı doğru kurmak, düz metin iş akışının tek gerçek bedelidir ve geçiştirmek yerine net bir cevabı hak eder.

En temiz varsayılan, secret değişkenidir. Bir ortamda, bir değişkenin secret kutucuğunu işaretlersiniz. Bruno o zaman o değeri içeride yönetir ve ortam dosyasına asla yazmaz; dosyaya yalnızca değişkenin adı işlenir. Git’e düşen şey addan ibarettir:

vars:secret [
  baseUrl
]

Değer yerel makinenizde yaşar; mümkün olduğunda OS düzeyinde şifreleme ile, o yoksa AES256’ya düşerek şifrelenir. Bruno ayrıca bir koleksiyonu export ettiğinizde secret değişkenleri ayıklar. Net etki, Bruno’nun ifadesiyle, “secret’larınızı ifşa etme endişesi olmadan koleksiyonunuzu güvenle versiyon kontrolüne check-in edebilirsiniz” olur. Bu, “ama token’larımı commit etmiş olmaz mıyım?” sorusunun doğrudan cevabıdır.

İkinci yol, çoğu backend mühendisinin zaten bildiği yoldur: koleksiyon klasörünün kökünde bir .env dosyası, Bruno içinde process.env üzerinden okunur. Belgelenmiş klasör yapısı, .env’in yanında bir .gitignore ile gelir; yani desen tanıdık olandır. .env git’ten dışlanmış kalır, istek dosyaları ile bruno.json ise commit edilir. Uygulamanız secret’ları zaten bu şekilde yönetiyorsa, koleksiyon da aynı kurala uyar ve yeni bir takım arkadaşı tek bir yerel dosyayı doldurur. Kurumsal ölçek için Bruno’nun Ultimate katmanı HashiCorp Vault, AWS Secrets Manager ve Azure Key Vault ile entegre olur; böylece değerler diske dokunmak yerine bir vault’tan çözülür. Bu, varsayılan yolun dışındaki ücretli seçenektir ve çoğu takımın asla ihtiyacı olmaz.

Takımlar bu disiplini atladığında iki hata kalıbı ortaya çıkar. İlki, vars:secret yerine düz bir vars bloğuna yapıştırılan gerçek bir token’ın herkese açık bir repo’ya push edilmesidir; değer geçmişe düşer ve orada kalır. Çözüm, secret kutucuğunu işaretleyip değerin dosyaya hiç ulaşmamasını sağlamak ya da onu git’ten dışlanmış .env’e taşımaktır. İkincisi daha sinsidir: koleksiyonu ara sıra yeniden ürettiğiniz bir export gibi görmek. Export edilip commit edilmiş bir JSON dökümü er geç drift demektir, çünkü kimse onu handler ile aynı PR içinde düzenlemez. Asıl mesele şu ki istek dosyası birinci sınıf bir kaynak dosyasıdır; aklınıza geldiğinde tazelediğiniz bir anlık görüntü olmak yerine kodla birlikte elle düzenlenir. Sınırı koleksiyonun README’sinde belgeleyin ki sonraki takım arkadaşı yerelde hangi dosyayı dolduracağını ve hangisine asla dokunmayacağını bilsin.

Bu Yaklaşımın Kaybettiği Durumlar

Düz metin iş akışı bir mühendislik takımı için varsayılandır, ama gerçek sınırları olan bir varsayılandır; aksini iddia etmek argümanı zayıflatır. Üç durum sizi bir bulut iş birliği aracına geri iter.

İlki, isteklerinizi çalıştıran ama git’e dokunmayacak kişilerdir. Giriş bedeli burada git’e hakimiyettir. Teknik olmayan bir QA testçisine ya da tıkla-çalıştır türünde paylaşılan bir çalışma alanına ihtiyaç duyan bir paydaşa, bir bulut aracı gerçekten daha iyi hizmet eder; isteklerinizi çalıştıranların kayda değer bir kısmı git bilmiyorsa, düz metin modeli sürtünmeyi azaltmak yerine artırır. İkincisi, ortak bir repo paylaşmayan takımlar arasında büyük ölçekli paylaşımdır. “Repo’muzu klonla” tek bir kod tabanı içinde gayet iyi bir onboarding adımıdır; ortak bir repo’nun olmadığı bir organizasyonda keşif mekanizması olarak ise dağılır ve burada organizasyon çapında aramaya sahip bir bulut çalışma alanı kazanır. Üçüncüsü, yerel öncelikli bir düz metin istemcisinin hiç sunmadığı yetenekler kümesidir: mock sunucular, monitor’ler, zamanlanmış sağlık kontrolleri, barındırılan dashboard’lar ve performans veya yük testi. Bruno açıkça yalnızca yereldir ve bulut senkronizasyonu yoktur; bunlar için bir bulut platformunda kalır ya da ayrı araçlar eklersiniz. Örneğin Postman, mock sunucuları, monitor’leri ve performans testini bulut özellikleri olarak sunar.

Postman karşılaştırmasını ölçülü ifade etmekte fayda var, çünkü üstünkörü hali yanlış. Postman hesap merkezli ve varsayılan olarak bulut-senkronludur: koleksiyonlar bir Postman hesabı ve çalışma alanında yaşar ve bilinçli olarak engellemediğiniz sürece buluta senkronize olur. Bu, Bruno’nun yerel öncelikli, dosyaları repo’nuzda tutan modelinden farklı bir ağırlık merkezidir ve asıl iş akışı kontrastı da işte bu farktır; kimse Postman’in hesapsız kullanılamayacağını iddia etmiyor. İki araç farklı şeyleri optimize eder. Biri hesap merkezli bir bulut çalışma alanını optimize eder; diğeri sözleşmeyi kodun yanında repo’da tutmayı.

Sonuç

İsteği çalıştıran kişilerin zaten git içinde yaşadığı bir mühendislik takımında düz metin koleksiyon varsayılandır; onu kod tabanının bir parçası gibi ele alın. Sınır üç yerde nettir ve bu durumlarla savaşmak yerine onları olduğu gibi kabul etmek gerekir: teknik olmayan istek çalıştırıcıları, ortak repo’su olmayan büyük ölçekli paylaşım ve mock sunucular ile monitor’ler gibi yalnızca bulutta olan yetenekler. İş akışının talep ettiği tek disiplin parçası bilinçli bir secret sınırıdır; bu yüzden pratik bir sonraki adım, ilk push’tan önce secret değişken kutucuğunu ya da git’ten dışlanmış bir .env’i kurmak ve her takım arkadaşının yerelde hangi dosyayı dolduracağını belgelemektir.

Kaynaklar

• Bru Markup Language - Bruno Docs - .bru’nun versiyon kontrollü koleksiyonlar için düz metin bir DSL olduğunu doğrular; OpenCollection YAML’ın artık yeni koleksiyonlar için önerilen format olduğunu belirtir.
• OpenCollection YAML - Bruno Docs - Bruno’nun artık yeni koleksiyonlar için önerdiği YAML spesifikasyonu; format değişikliği uyarısıyla ilgilidir.
• Secret Management overview - Bruno Docs - Secret’ların check-in veya export öncesi ayıklanması gerektiğini belirtir; üç secret yaklaşımını sıralar.
• Secret Variables - Bruno Docs - secret kutucuğu; değerler ortam dosyasına yazılmaz (vars:secret [...]), OS şifrelemesi veya AES256 ile saklanır. Commit etmesi güvenli varsayılan desen.
• DotEnv File - Bruno Docs - Koleksiyon kökünde bir .env artı .gitignore, process.env üzerinden erişilir; tanıdık backend deseni.
• Secret Managers overview - Bruno Docs - HashiCorp Vault, AWS Secrets Manager ve Azure Key Vault entegrasyonu, Bruno Ultimate’a kilitli.
• Bruno (GitHub deposu) - CI için @usebruno/cli ve bru run, ve ayrı bir “Bru” dili gösteren dil dağılımı.
• Bruno LICENSE - MIT Lisansı, Copyright (c) 2022 Anoop M D, Anusree P S and Contributors. Çekirdeğin MIT olduğunu, source-available veya ticari olmadığını doğrular.
• Bruno en son sürüm (GitHub) - En son yayınlanan sürüm etiketi ve değişiklik günlüğü.
• Bruno Fiyatlandırma - Kullanıcı başına aylık Open Source, Pro ve Ultimate katmanları, yıllık faturalandırılır. Git-içinde-repo iş akışı yalnızca ücretsiz çekirdeğe ihtiyaç duyar.
• Bruno ana sayfası - “Git-native API istemcisi,” “Yalnızca Yerel,” “Kod olarak saklanan koleksiyonlar.” Bruno’nun kendi konumlandırmasının birincil kaynağı.
• About Postman accounts - Postman Docs - Postman’in hesap merkezli, varsayılan bulut-senkronlu modeli; kontrast noktası.
• Install Postman - Postman Docs - Web’e karşı masaüstü özellik ayrımı; yalnızca-bulut özellikleri noktasını destekler (mock sunucular, monitor’ler, performans testi).