Brunoはリクエストファーストですか？はい、BrunoはHTTPリクエストの作成、整理、送信を中心に構築されています。コレクションを作成し、リクエストを追加し、それらを.bruファイルに記述し、実行し、その全体をGitでバージョン管理します。このモデルは高速でGitフレンドリーであり、既存のAPIを探索する際には純粋な喜びを感じられます。
しかし、「リクエストファースト」と「デザインファースト」は異なる質問に答えます。リクエストファーストは「このエンドポイントをどのように呼び出すのか？」と尋ねます。デザインファーストは「誰もコードを書き始める前に、このエンドポイントはどうあるべきか？」と尋ねます。この2つの質問の間のギャップこそ、新しいAPIや共有APIを構築するチームが摩擦を感じ始める場所です。この記事では、Brunoのリクエストファーストとデザインファーストのトレードオフについて正直に説明し、OpenAPIネイティブなデザインファーストワークフローがその価値を発揮する場面を示します。
リクエストファースト vs デザインファースト、手短に
これら2つのアプローチは、競合というよりも異なる出発点です。以下に概要をまとめます。
| 側面 | リクエストファースト (Bruno) | デザインファースト (OpenAPIネイティブ) |
|---|---|---|
| 出発点となる成果物 | 送信可能なリクエスト | 契約 (OpenAPI仕様) |
| 最適な用途 | 既存APIの探索とテスト | コード作成前の新規/共有APIの設計 |
| 信頼できる情報源 | リクエストのコレクション | 仕様書 |
| チーム横断レビュー | エンドポイントが存在した後 | サーバーコードを1行も書く前 |
| 視覚的な設計インターフェース | デフォルトではなし | ビジュアルデザイナー + スキーマエディタ |
| ドリフトのリスク | コレクションが実際のAPIに遅れる可能性 | 仕様書が唯一の契約として維持される |
| Gitとの連携 | 強力 (プレーンテキストの.bru) |
ツールが仕様書をGitと同期する場合に強力 |
どちらの列も「間違っている」わけではありません。適切な選択は、APIがすでに存在するか、現在定義中かによって異なります。
Brunoのリクエストファーストモデル
Brunoはその役割をうまく果たしており、その役割が何であるかを正確に把握しておく価値があります。Brunoはリクエストを、ユーザーが所有するフォルダ内のプレーンテキストの.bruファイルとして保存します。必須のクラウドアカウント、独自の同期機能、オプトアウトが必要なバックグラウンドテレメトリーはありません。APIクライアントが他のコードベースと同じように動作することを望む開発者にとって、これは真の利点であり、多くのチームが採用しているGitネイティブAPIワークフローの核となるものです。
Brunoが輝く場面:
- 既存のAPIの探索。実行中のサービスを指し、リクエストを発行し、レスポンスを検査し、反復します。フィードバックループは非常にタイトです。
- ローカルファーストでGitフレンドリー。差分は読みやすく、マージは理にかなっており、リクエスト履歴はコードと同じPRに存在します。
- スクリプトとテスト。リクエストの前後のスクリプト、アサーション、環境変数は、ほとんどのエンジニアが必要とする日常的なテストをカバーします。
- ロックインなし。形式はオープンで、ファイルはユーザーのものです。
もしあなたの仕事が、既存のAPIを利用し、検証することであれば、リクエストファーストが最も直接的な方法となることが多いです。これは以前、このBrunoの代替ツールの比較記事で、より広範なプラットフォームと比較した際に述べたことでもあります。
設計層や契約層がないことのコスト
このトレードオフは、APIがまだ存在しない場合や、複数のチームがAPIがどうあるべきかについて合意しなければならない場合に顕著になります。
ビジュアルデザイナーがない。リクエストファーストツールは、エンドポイントをリソース、スキーマ、レスポンスのモデルとしてではなく、リクエストとして表現します。プロダクトエンジニア、バックエンドリーダー、フロントエンド開発者が、誰もハンドラーを書く前に同じリソースの形を見て合意できるようなキャンバスはありません。リクエストで設計するということは、例で設計するということであり、例は構造を強制しません。
契約のずれ。コレクションが信頼できる情報源である場合、それは誰かがすでに呼び出したものを反映しているにすぎません。実際のAPIは変更され、フィールドが追加されたり、パラメーターが非推奨になったり、検証が厳しくなったりする可能性があり、その結果、テストが失敗するまでコレクションはひっそりと遅れていきます。仕様中心のワークフローでは、この関係が逆転します。契約が参照元であり、実装はそれに照らしてチェックされます。
コード作成前のチーム横断レビューがより困難。リクエストのフォルダをレビューすることで、エンドポイントが今日どのように呼び出されているかがわかります。しかし、実装前に承認するための、クリーンで宣言的なドキュメントをレビューアに提供するものではありません。デザインレビューを通じてAPIの変更をゲートしているチームにとって、第一級の契約がないことは、そのレビューを遅くし、アドホックなものにします。
これらがいずれもBrunoを劣悪なツールにするわけではありません。Brunoは、リクエストファーストとしての本来の仕事以外で使われるリクエストファーストツールになるというだけです。
デザインファーストが勝利する時
デザインファーストは特に次の3つの状況で成果を上げます。
- グリーンフィールドAPI。まだ何も存在しない場合、仕様書が設計そのものです。リソース、スキーマ、エラーの形を一度定義し、その単一の契約からサーバーのスタブ、モック、ドキュメントを生成します。後でリクエストから逆行してエンジニアリングする必要はありません。
- 複数チーム間の契約。バックエンドチームと1つ以上のクライアントチームが合意する必要がある場合、OpenAPI仕様が合意そのものとなります。フロントエンドは、実際のherokuappを待つのではなく、契約が承認された瞬間にモックに対して構築を開始でき、バックエンドの実装と並行して作業を進めることができます。
- 公開API。外部の開発者があなたに依存している場合、安定性と明確なドキュメントが製品となります。維持された契約は、生成された参照ドキュメント、バージョン管理の規律、そして破壊的変更を意図的に伝達する方法を提供します。
共通するテーマ：デザインファーストは、APIが、コードが提供される後にただいじくり回すサービスではなく、コードが書かれる前に合意が必要な共有インターフェースである場合に勝利します。
Apidogのデザインファーストとスペックファーストモード
Apidogはデザインファーストで構築されており、ここで重要な点は、OpenAPIネイティブでGitフレンドリーな体験を諦める必要がないことです。
同じプロジェクトに対して2つの方法で作業できます。エンドポイント、リクエストおよびレスポンススキーマ、再利用可能なコンポーネントをYAMLを手書きすることなく定義するためのビジュアルデザイナーは、ほとんどの人が「デザインファースト」と聞いて思い描くものです。そして、OpenAPIドキュメントを直接作成するコードエディタであるスペックファーストモードがあり、仕様書が文字通りの信頼できる情報源となります。これら2つは同期を保つため、バックエンドエンジニアが生のOpenAPIで作業する一方で、プロダクトエンジニアはキャンバス上で作業でき、両者が同じ契約を編集していることになります。
スペックファーストモードは双方向のGit同期もサポートしています。仕様書は実際のファイルとしてリポジトリに存在し、変更は両方向に流れ、APIデザインはコードと同じプルリクエストとレビューを通過します。これはBrunoユーザーが評価するGitネイティブな特性であり、リクエストのコレクションではなく契約に適用されます。詳細な仕組みはスペックファーストモードのドキュメントに記載されています。
その結果、両方の質問をカバーする1つのワークフローが実現します。必要に応じて最初に契約を設計し、エンドポイントが稼働したらリクエストファーストのクライアントのようにそれに対してテストを行うことができます。これらのモデルがどこで出会うかについてより深く知るには、Apidogにおけるスペックファースト vs デザインファーストをご覧ください。
チームの成熟度による選択
決定を下す簡単な方法は、ツールを好みに合わせるのではなく、APIのライフサイクルにおける段階に合わせることです。
- ソロまたは小規模チームで、主にAPIを利用する場合。リクエストファーストで十分です。Brunoのローカルファーストモデルは邪魔にならず、不要な公式契約を維持するオーバーヘッドを負う必要もありません。
- 自社APIをリリースする成長中のチーム。これが転換点です。2つ目のチームがあなたのエンドポイントに依存するようになると、非公式なコレクションはスケーリングしなくなり、明示的な契約がレビューサイクルと統合バグの削減に貢献し始めます。
- 公開APIや多数の内部APIを持つ成熟した組織。デザインファーストが事実上必須となります。仕様書はガバナンス、ドキュメント、オンボーディングのすべてを一度に提供し、Git同期を備えたOpenAPIネイティブツールはそれを正確に保ちます。
Brunoのリクエストファーストとデザインファーストに関する正直な見解は、通常、好みではなく成熟度が決定要因になるということです。チームはリクエストファーストで始まり、APIが他の人々が依存する契約となるにつれてデザインファーストへと成長する傾向があります。
FAQ
Brunoはリクエストファーストですか、それともデザインファーストですか？
Brunoはリクエストファーストです。そのコアモデルは、プレーンテキストファイルとして保存されたリクエストを作成、整理、送信することであり、これは既存のAPIを探索しテストするのに理想的です。APIが構築される前にOpenAPI契約を作成することを中心にはしていません。
Brunoでデザインファーストの作業はできますか？
仕様中心のツールが行うようなネイティブな方法ではできません。Brunoは、信頼できる情報源としてのビジュアルデザイナーやOpenAPIドキュメントではなく、リクエストに焦点を当てています。コードの前に契約を定義してレビューする必要がある場合、デザインファーストでOpenAPIネイティブなツールの方がその仕事に適しています。
デザインファーストに移行するためにGitフレンドリーさを諦める必要がありますか？
いいえ。Gitネイティブな特性、つまりリポジトリ内のプレーンテキストファイル、読みやすい差分、PRを通じたレビューは、仕様書自体にも適用できます。Apidogのスペックファーストモードは、OpenAPIドキュメントを双方向同期でリポジトリに保持するため、デザインファーストがGitを置き去りにすることを意味しません。