DEV Community

Cover image for Bruno Request-First？デザインファーストツールが必要な時
Akira
Akira

Posted on • Originally published at apidog.com

Bruno Request-First？デザインファーストツールが必要な時

Brunoはリクエストファーストです。HTTPリクエストを作成し、コレクションに整理し、.bruファイルとして保存し、実行し、Gitでバージョン管理する流れを中心に設計されています。既存APIを探索・検証する場合、このモデルは高速で扱いやすく、開発者にとって自然です。

今すぐApidogを試す

ただし、「リクエストファースト」と「デザインファースト」は解く問題が違います。

  • リクエストファースト: このエンドポイントをどう呼び出すか？
  • デザインファースト: 実装前に、このエンドポイントはどうあるべきか？

新規APIや複数チームで共有するAPIでは、この違いが設計レビュー、契約管理、実装のずれに直結します。この記事では、Brunoのリクエストファーストモデルの強みと限界を整理し、OpenAPIネイティブなデザインファーストワークフローが有効になる場面を実装目線で説明します。

リクエストファースト vs デザインファースト

側面 リクエストファースト（Bruno） デザインファースト（OpenAPIネイティブ）
出発点 送信可能なHTTPリクエスト API契約（OpenAPI仕様）
主な用途 既存APIの探索・テスト 実装前のAPI設計
信頼できる情報源 リクエストコレクション OpenAPI仕様
レビューのタイミング エンドポイント実装後 サーバー実装前
設計UI デフォルトではなし ビジュアルデザイナー、スキーマエディタ
ドリフトのリスク 実APIとコレクションがずれる可能性 仕様を契約として維持
Gitとの相性 強い（プレーンテキストの.bru） 仕様ファイルをGit同期できれば強い

どちらが正しいかではなく、APIがすでに存在するのか、これから定義するのかで選択が変わります。

Brunoのリクエストファーストモデル

Brunoは、リクエストをユーザーが管理するフォルダ内のプレーンテキスト.bruファイルとして保存します。必須のクラウドアカウントや独自同期に依存せず、APIクライアントをコードベースと同じように扱えます。

これは、多くのチームが採用するGitネイティブAPIワークフローと相性が良い点です。

Bruno request-first workflow

Brunoが向いているケースは次のとおりです。

  • 既存APIを探索する
  • 実行中のサービスに対してリクエストを送り、レスポンスを確認する
  • リクエストをGitで管理する
  • PR上で.bruファイルの差分を確認する
  • 環境変数、事前スクリプト、事後スクリプト、アサーションで日常的なAPIテストを行う
  • クラウド同期やベンダーロックインを避ける

たとえば、既存APIを検証する場合は次のような流れになります。

# 1. APIリクエストをBrunoで作成
# 2. .bruファイルをリポジトリに保存
# 3. 変更をGitで確認
git diff

# 4. APIリクエストの変更をPRでレビュー
git add .
git commit -m "Add user API request collection"
Enter fullscreen mode Exit fullscreen mode

APIを利用する、または検証することが主な目的なら、リクエストファーストは最短ルートです。この観点は、以前のBruno代替ツールの比較記事でも扱っています。

設計層や契約層がない場合のコスト

リクエストファーストは既存APIに強い一方で、APIがまだ存在しない場合や複数チームで仕様を合意する場合には摩擦が出ます。

1. 実装前の設計がしづらい

リクエストファーストツールでは、エンドポイントは主に「送信するリクエスト」として表現されます。

しかし、新規APIでは次のような設計を先に決める必要があります。

paths:
  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: User found
Enter fullscreen mode Exit fullscreen mode

このようなリソース、パラメータ、レスポンス、スキーマの構造をチームで確認するには、OpenAPI仕様のような契約が必要です。

リクエスト例だけで設計すると、次の問題が起きやすくなります。

  • フィールドの必須・任意が曖昧になる
  • エラー形式が統一されない
  • 複数エンドポイントでスキーマが重複する
  • 実装後に仕様の認識違いが発覚する

2. API契約が実装から遅れる

リクエストコレクションが信頼できる情報源になる場合、それは「誰かが呼び出したことのあるAPI」を反映しているだけです。

実API側で次のような変更があっても、コレクションが追従しない可能性があります。

  • レスポンスフィールドの追加
  • パラメータの非推奨化
  • バリデーションルールの変更
  • エラーコードの追加
  • 認証方式の変更

仕様中心のワークフローでは、この関係を逆にします。

OpenAPI仕様
   ↓
モック生成
   ↓
サーバー実装
   ↓
テスト
   ↓
ドキュメント生成
Enter fullscreen mode Exit fullscreen mode

契約が先にあり、実装はその契約に対して検証されます。

3. 実装前レビューが難しい

リクエストのフォルダをレビューすれば、エンドポイントが現在どう呼ばれているかは分かります。

しかし、実装前に次のような観点をレビューするには不十分です。

  • API名は適切か
  • リソース設計は一貫しているか
  • スキーマは再利用できるか
  • エラー形式は統一されているか
  • クライアントチームが実装を開始できるか
  • 破壊的変更が含まれていないか

API変更を設計レビューでゲートするチームでは、第一級のAPI契約がないとレビューが属人的になります。

デザインファーストが有効なケース

デザインファーストは、特に次のケースで効果を発揮します。

1. グリーンフィールドAPI

まだAPIが存在しない場合、OpenAPI仕様が設計そのものになります。

実装前に次を定義できます。

components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: string
        email:
          type: string
          format: email
Enter fullscreen mode Exit fullscreen mode

この仕様から、以下を生成・利用できます。

  • モックAPI
  • APIドキュメント
  • サーバースタブ
  • クライアントSDK
  • 契約テストの基準

リクエストから後で逆算する必要がありません。

2. 複数チーム間の契約

バックエンドチームとフロントエンドチームが同じAPIに依存する場合、OpenAPI仕様が合意の中心になります。

実装フローは次のようになります。

1. OpenAPI仕様を作成
2. チームでレビュー
3. モックAPIを公開
4. フロントエンドはモックに対して実装開始
5. バックエンドは仕様に沿って実装
6. 実APIを契約に対して検証
Enter fullscreen mode Exit fullscreen mode

これにより、フロントエンドはバックエンド実装の完了を待たずに作業できます。

3. 公開API

外部開発者が利用するAPIでは、ドキュメントと安定性がプロダクトの一部です。

OpenAPI仕様を維持すると、次が可能になります。

  • 参照ドキュメントの自動生成
  • バージョン管理
  • 破壊的変更の明示
  • SDK生成
  • 利用者向けオンボーディングの改善

Design-first API workflow

共通するポイントは、APIが単なる実装済みサービスではなく、複数の開発者が依存する共有インターフェースになることです。

Apidogのデザインファーストとスペックファーストモード

ApidogはデザインファーストでAPIを扱えるツールです。重要なのは、OpenAPIネイティブでありながら、Gitフレンドリーな運用もできる点です。

Apidog design-first mode

Apidogでは、同じAPIプロジェクトに対して主に2つの作業方法があります。

1. ビジュアルデザイナーで設計する

YAMLを直接書かなくても、次をGUI上で定義できます。

  • エンドポイント
  • HTTPメソッド
  • パスパラメータ
  • クエリパラメータ
  • リクエストボディ
  • レスポンススキーマ
  • 再利用可能なコンポーネント
  • 認証設定

プロダクトエンジニアやフロントエンド開発者も、APIの形を視覚的に確認できます。

2. スペックファーストモードでOpenAPIを直接編集する

スペックファーストモードでは、OpenAPIドキュメントを直接編集できます。

openapi: 3.0.3
info:
  title: User API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users
      responses:
        "200":
          description: OK
Enter fullscreen mode Exit fullscreen mode

バックエンドエンジニアは生のOpenAPIを編集し、他のメンバーはビジュアルUIで同じ契約を確認できます。

この2つは同期されるため、チーム全体が同じAPI契約を編集できます。

Git同期でAPI契約をPRレビューに乗せる

Apidogのスペックファーストモードは、双方向のGit同期もサポートしています。

仕様ファイルをリポジトリで管理できるため、API設計を通常のコードレビューに組み込めます。

api/
  openapi.yaml
src/
  handlers/
tests/
Enter fullscreen mode Exit fullscreen mode

運用イメージは次のとおりです。

# OpenAPI仕様を変更
vim api/openapi.yaml

# 差分を確認
git diff api/openapi.yaml

# PRでAPI設計をレビュー
git add api/openapi.yaml
git commit -m "Update user API contract"
Enter fullscreen mode Exit fullscreen mode

Brunoが.bruファイルで実現するGitネイティブ性を、ApidogではOpenAPI契約に適用できます。

詳しくはスペックファーストモードのドキュメントを参照してください。

Apidog spec-first mode

結果として、次の2つの問いを1つのワークフローで扱えます。

  • 実装前: このAPIはどうあるべきか？
  • 実装後: このAPIをどう呼び出し、どう検証するか？

スペックファーストとデザインファーストの関係については、Apidogにおけるスペックファースト vs デザインファーストも参考になります。

チームの成熟度で選ぶ

ツール選定は、好みよりもAPIライフサイクルに合わせると判断しやすくなります。

ソロ開発または小規模チーム

主に既存APIを利用・検証するなら、リクエストファーストで十分です。

BrunoのようなローカルファーストのAPIクライアントは、不要な契約管理を増やさずに済みます。

適した運用:

既存API
  ↓
リクエスト作成
  ↓
レスポンス確認
  ↓
テスト追加
  ↓
Gitで管理
Enter fullscreen mode Exit fullscreen mode

自社APIを複数チームに提供する成長中のチーム

2つ目のチームがAPIに依存し始めたら、明示的な契約が必要になります。

この段階では、非公式なリクエストコレクションだけではスケールしにくくなります。

導入すべき運用:

OpenAPI仕様を作成
  ↓
設計レビュー
  ↓
モック共有
  ↓
実装
  ↓
契約に対して検証
Enter fullscreen mode Exit fullscreen mode

公開APIや多数の内部APIを持つ組織

公開APIや大規模な内部APIでは、デザインファーストがほぼ必須になります。

仕様は次の役割をまとめて担います。

  • ガバナンス
  • ドキュメント
  • オンボーディング
  • バージョン管理
  • 破壊的変更の管理
  • SDK生成の基準

Brunoのリクエストファーストとデザインファーストの違いは、優劣ではなく成熟度の問題です。多くのチームはリクエストファーストから始め、APIが他チームや外部開発者に依存される契約になるにつれて、デザインファーストへ移行します。

FAQ

Brunoはリクエストファーストですか、それともデザインファーストですか？

Brunoはリクエストファーストです。中心となるモデルは、プレーンテキストファイルとして保存されたリクエストを作成、整理、送信することです。既存APIの探索やテストに向いていますが、実装前にOpenAPI契約を作成・レビューすることを主目的にはしていません。

Brunoでデザインファーストの作業はできますか？

仕様中心ツールと同じネイティブな方法ではできません。BrunoはOpenAPI契約やビジュアル設計キャンバスではなく、リクエストを中心に扱います。

コードを書く前にAPI契約を定義し、複数チームでレビューする必要がある場合は、OpenAPIネイティブなデザインファーストツールの方が適しています。

デザインファーストに移行するとGitフレンドリーさを失いますか？

いいえ。Gitネイティブな運用は、リクエストファイルだけでなくOpenAPI仕様にも適用できます。

Apidogのスペックファーストモードでは、OpenAPIドキュメントをリポジトリ内のファイルとして管理し、双方向同期できます。これにより、API設計を通常のPRレビューに組み込めます。

Top comments (0)