APIをGitネイティブに設計・開発する方法

ほとんどのAPIチームは、契約を後回しにしています。まずコードを書き、次に仕様書を生成し、その後、その2つが乖離していくのを見ています。GitネイティブAPIデザインはその順序を逆転させます。API契約をソースコードとして扱い、Gitでバージョン管理し、アプリケーションロジックをレビューするのと同じ方法ですべての変更をレビューします。

このガイドは、単一のツールではなく、規律についてです。ブランチで契約を設計し、プルリクエストでレビューし、コミットされた仕様書をモック、テスト、ドキュメントに変換する方法を学びます。目標は、Git履歴がAPI履歴となるワークフローを構築することです。

もしあなたがすでにSpec-Firstツールがどのようなものかを知っていて、製品のウォークスルーを望むなら、gitネイティブAPIワークフローに関する補足記事を読んでください。この記事は実践に焦点を当てています。

API作業における「Gitネイティブ」とは

Gitネイティブとは、API定義がプレーンテキストファイルとしてリポジトリに存在することを意味します。独自のクラウドデータベースではなく、ベンダーのログインの裏にあるのでもありません。チームがすでに使用しているバージョン管理によって追跡される、コードの隣にある.yamlまたは.jsonファイルです。

これをクラウドにロックされたツールと比較してみましょう。多くのAPIデザインプラットフォームは、契約を独自のバックエンドに保存します。Web UIを通じて編集し、正規のバージョンはそれらのサーバーに存在します。リポジトリにはせいぜい古いエクスポートが残るだけです。ベンダーのデータベースが信頼できる情報源である場合、Gitの履歴はAPIがどのように進化したかについて何も教えてくれません。

Gitネイティブモデルはその関係を逆転させます。mainにあるファイルが契約です。GUIを含む他のすべては、そのファイルに対するビューです。この単一の変更により、APIサーフェスの履歴、責任、ロールバック、およびレビューが可能になります。

Gitネイティブのセットアップには3つの特性があります。仕様はリポジトリ内のテキストファイルであること。変更は、ブランチ、コミット、マージなどの通常のGit操作を通じて流れること。そして、モックからドキュメントまで、すべてのダウンストリーム成果物は、個別のデータベースではなく、コミットされたファイルから派生することです。

APIをGitで設計・開発する理由

あなたはすでにGitを最も貴重な資産であるコードで信頼しています。あなたのAPI契約も同じ扱いを受けるべきです。

最初の理由は履歴です。「いつcursorページネーションパラメーターを追加したのか」と誰かが尋ねたとき、git logは数秒で答えます。それを導入したコミットには、メッセージ、作成者、日付が含まれています。スクリーンショットも、変更ログの考古学も不要です。

2番目の理由は責任追跡です。仕様ファイルでgit blameを実行すると、誰がどの行を変更し、その理由が正確にわかります。混乱を招くフィールド名は、それ追加したPRまで遡り、議論が添付されています。説明責任は自動的になります。

3番目の理由はロールバックです。悪いデザインが出荷されてしまいました。Gitを使用すると、git revertでマージを元に戻し、契約は以前の状態に戻ります。ダウンストリームのコード生成、モック、ドキュメントは、元に戻されたファイルから再生成されます。個別のシステムでの手動クリーンアップは必要ありません。

4番目の理由はレビューであり、これはチームがあまり活用していないものです。プルリクエストは、APIデザインが現実になる前に議論する自然な場所です。レビュー担当者は、必須フィールドを追加する+行にコメントします。その議論は常に変更と共存します。

単一の信頼できる情報源がすべてを結びつけます。契約がmainの1つのファイルにある場合、どのバージョンが本物であるかについて曖昧さはありません。フロントエンド、バックエンド、QA、ドキュメントのすべてが同じYAMLの行を読み取ります。これは、GitベースのAPI仕様ワークフローの核心的な約束です。

GitネイティブAPIデザインループ

このループには5つのステップがあります。契約を設計し、コミットし、PRを開き、レビューし、マージします。実装はマージの後に行われ、その逆ではありません。

まず契約の作成から始めます。ユーザーの請求書を取得するためのエンドポイントを追加するとします。ブランチを作成し、OpenAPIファイルを編集します。

# openapi.yaml (feat/invoices-list ブランチで追加された抜粋)
paths:
 /users/{userId}/invoices:
 get:
 operationId: listUserInvoices
 summary: ユーザーの請求書を一覧表示
 parameters:
 - name: userId
 in: path
 required: true
 schema: { type: string, format: uuid }
 - name: status
 in: query
 required: false
 schema:
 type: string
 enum: [draft, open, paid, void]
 responses:
 "200":
 description: 請求書のページ
 content:
 application/json:
 schema:
 $ref: "#/components/schemas/InvoiceList"
 "404":
 description: ユーザーが見つかりません

その変更を明確なメッセージでコミットします：git commit -m "GET /users/{userId}/invoices 契約を追加"。このコミットは小さく、焦点を絞っています。それは1つの設計決定を記述しています。

次にプルリクエストを開きます。差分はレビュー担当者に何が新しいのかを正確に示します。1つのパス、1つの操作、2つのパラメーター、2つのレスポンスです。チームメイトは命名、列挙値、そして404がユーザーが見つからない場合の適切なコードであるかどうかを議論します。彼らはハンドラーコードが1行も存在しないうちにカーソルページネーションを強く推奨するかもしれません。

PRが承認されたら、それをマージします。これでmainの契約には請求書エンドポイントが含まれることになります。実装が次に続き、それは全員が合意した仕様によって制約されます。この順序付けこそが、スペックファーストAPI開発が意味するところです。つまり、合意がコードに先行するということです。

その報酬は、設計に関する議論が安価に行われることです。レビューでYAMLフィールドを変更するコストは数分です。出荷済み、実装済み、文書化済みのエンドポイントを変更するコストは数日かかります。

API契約のブランチ戦略

契約の変更は他の変更と同じように扱います。作業の論理単位ごとに1つのブランチを使用します。エンドポイントごと、または変更ごとにブランチを作成することで、PRを小さく保ち、差分を読みやすくします。

意図が明確になるようにブランチに名前を付けます。変更の種類を示すプレフィックスを使用します。これはレビュー担当者やCIが作業をルーティングするのに役立ちます。

プレフィックスには意味があります。break/api-ブランチは、レビュー担当者に注意深くすべてのコンシューマをチェックするように伝えます。chore/api-ブランチは意味的な変更がないことを示唆しているため、レビューを迅速に進めることができます。

また、ブランチモデルも選択します。トランクベース開発はほとんどのAPIチームに適しています。短い期間のブランチが毎日mainにマージされ、仕様は単一の真実に近い状態を保ちます。長い期間のdevelopおよびreleaseブランチを持つGitflowは、API変更を定期的なリリースにまとめるチームに適しています。

ほとんどのAPI作業では、トランクベースを推奨します。小さく頻繁な契約変更は、小さく頻繁な差分を生み出します。長期間のブランチでは仕様が乖離し、2つのブランチが同じファイルを再構築すると、YAMLのマージコンフリクトがすぐにひどいことになります。

プルリクエストでのAPIデザインレビュー

仕様のPRはデザインレビューであり、構文チェックではありません。レビュー担当者はセマンティクスをチェックし、いくつかの質問でほとんどのリスクをカバーできます。

これは既存のコンシューマを破壊するか？フィールドの削除、パスの名前変更、型の厳格化はすべて破壊的変更です。レビュー担当者は、変更が追加的なものか破壊的なものかをチェックし、破壊的変更はバージョンアップまたは非推奨パスを要求します。

命名は一貫しているか？すべてのコレクションエンドポイントが複数形の名詞を使用している場合、新しい単数形のパスは目立ちます。エラーが他の場所でcodeフィールドを返す場合、新しいエンドポイントもそうすべきです。レビュー担当者は、APIがすでに確立しているパターンを強制します。

差分に優しいか？YAMLを安定させて、差分が小さく保たれるようにします。キーの順序を一貫させます。新しいパスは予測可能な場所に追加します。レビュー担当者は5行の差分を数秒で読むことができますが、再編成されたファイルは、実際の変更を隠す100行の差分を生成します。

レビュー担当者に優しい破壊的変更。-行は、何が消えるかを正確に示します。

# PRでレビュー担当者が見る差分
 parameters:
 - name: status
 in: query
 schema:
 type: string
- enum: [draft, open, paid, void]
+ enum: [draft, open, paid, void, uncollectible]

この差分は列挙型への追加であるため安全です。これを、voidを完全に削除する-行と比較してください。これはその値を送信しているクライアントをすべて破壊します。差分は一目で違いを視覚的に示します。

レビュー担当者には、コードにコメントするのと同じように、仕様にインラインでコメントするよう奨励してください。議論は行に添付され、マージされた履歴に残ります。

設計から開発へ

契約がmainに入ると、それはダウンストリームのすべてにとってのソースとなります。あなたは手書きではなく、生成します。

最初にコード生成が行われます。openapi-generatorのようなツールは、コミットされたファイルからサーバスタブと型付きクライアントを生成します。ハンドラーはビジネスロジックを埋めますが、リクエストとレスポンスの形状は設計によって契約と一致します。仕様とコードはワイヤーフォーマットについて不一致を起こすことはありません。

次にモックです。モックサーバーは仕様を読み込み、すべてのエンドポイントの例のレスポンスを返します。フロントエンド開発者は、バックエンドが存在する前にモックに対して開発を行います。契約がマージされた瞬間から開始し、数週間後ではありません。

テストが続きます。契約テストは、実行中のサーバーが仕様と一致することをアサートします。リクエストを送信し、スキーマに対してレスポンスを検証し、乖離していればビルドを失敗させます。これは仕様とコードの乖離に対する防衛策です。

ドキュメントも生成されます。リファレンスドキュメントはOpenAPIファイルから直接レンダリングされます。契約が変更されると、ドキュメントも同じコミットで変更されます。個別のドキュメント更新を忘れることはありません。

原則は一貫しています。すべての成果物は、コミットされた1つのファイルから派生します。マージごとに再生成することで、モック、クライアント、テスト、およびドキュメントが契約と同期して維持されます。

チームの成長に対応するチーム規約

チームが成長してもGitネイティブワークフローが崩壊しないようにするのが、規約です。早期に決定し、文書化してください。

まず、1つの仕様ファイルか多数の仕様ファイルかを選択します。単一のopenapi.yamlはシンプルですが、数十のエンドポイントを超えると扱いにくくなります。$ref参照を使って複数のファイルに分割することで、バンドルステップが必要になるものの、各ファイルを読みやすく保てます。一般的なパターンは、リソースごとに1つのファイルを作成し、ビルド時に単一の仕様にバンドルすることです。

次に、意図的にバージョン管理を行います。意味のある変更ごとにOpenAPIのinfo.versionを更新し、セマンティックバージョニングに従います。追加的な変更はマイナーバージョンを更新します。破壊的変更はメジャーバージョンを更新し、通常、/v2/のような新しいパスプレフィックスを意味します。

3番目に、変更履歴を記録します。仕様の隣にあるCHANGELOG.mdは、何がどのように変更されたかを人間が理解できる言葉で記録します。Gitの履歴は正確ですが冗長です。変更履歴は、コンシューマーが実際にスキャンする読みやすい要約です。

4番目に、CODEOWNERSで仕様を保護します。契約ファイルへの変更はすべてAPI管理者が承認することを義務付けます。これにより、善意の貢献者が一貫性のない設計を出荷するのを防ぎます。

# .github/CODEOWNERS
/api/openapi.yaml @api-stewards
/api/paths/ @api-stewards

5番目に、CIでリンティングを行います。リンターは、レビュー前にスタイルと一貫性の問題を検出します。すべてのPRで実行することで、人間はフォーマットではなくデザインをレビューします。

# .github/workflows/api-lint.yml
name: API Lint
on:
 pull_request:
 paths: ["api/"]
jobs:
 spectral:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 - name: Run Spectral
 run: npx @stoplight/spectral-cli lint api/openapi.yaml --fail-severity warn

CIリンティングとCODEOWNERSを組み合わせることで、すべての契約変更が自動チェックと人間の管理者によるレビューを受けることができます。この組み合わせは、3人のエンジニアから300人までスケールします。

よくある落とし穴とその回避策

GitネイティブAPI設計には予測可能な失敗パターンがあります。それらを知ることで、回避策を設計できます。

最悪なのは仕様とコードの乖離です。契約はこう言っているのに、実行中のサーバーは違うことをしています。これを防ぐには、CIで契約テストを追加し、コミットされた仕様に対してライブレスポンスを検証します。乖離があればビルドは失敗します。乖離は本番でのサプライズではなく、壊れたパイプラインとなります。

次に大きなPRの罠があります。20のエンドポイントを追加する単一のブランチは、レビューできないほどの差分を生成します。レビュー担当者はざっと見て承認し、問題を見逃します。作業はPRごとに1つのエンドポイントまたは1つの変更に分割します。小さな差分は実際にレビューされます。

手書きの成果物は、静かな不整合を引き起こします。誰かがクライアントを生成せずに手書きすると、クライアントは仕様から乖離します。クライアント、スタブ、ドキュメントは、コミットされたファイルから毎回生成します。手書きのAPI成果物は不健全な兆候と見なすべきです。

YAMLのマージ競合は、長期ブランチを使用するチームを苛立たせます。2つのブランチが同じファイルを再構築し、Gitはそれらを調停できません。これを回避するには、短期ブランチ、安定したキーの順序、および変更が異なるファイルに触れるようにファイルを分割したレイアウトを使用します。トランクベース開発と小さなPRを組み合わせることで、ほとんどの競合が始まる前に解決されます。

これら4つすべてのパターンは同じです。変更を小さく保ち、仕様から成果物を派生させ、CIに契約を強制させます。規律は英雄的な行動に勝ります。

Apidogの役割

テキストエディタとCLIでGitネイティブなワークフローを実行できます。多くのチームは、Gitを信頼できる情報源として維持しながら、デザインにGUIを求めます。ApidogのSpec-Firstモードは、このギャップを埋めます。

Spec-Firstモードは、OpenAPIファイルをGitリポジトリに保持し、双方向同期を備えています。Apidogのビジュアルデザイナーまたはエディタで契約を編集すると、両方がリポジトリ内のファイルと一貫性を保ちます。Git内のファイルは正規のままであるため、ブランチ、PR、履歴はすべてここに記載されているとおりに機能します。クラウドロックインなしでGUIを利用できます。セットアップの詳細については、Spec-Firstモードのドキュメントを参照してください。

重要なのはツールではありません。ビジュアルなデザインサーフェスとGitネイティブな規律を同時に持つことができるということです。リポジトリは信頼できる唯一の情報源であり、Apidogはそのビューの一つとなります。

FAQ

GitネイティブAPIデザインはOpenAPI専用ですか？

いいえ。この規律は、テキストベースのあらゆる契約フォーマットに適用されます。OpenAPIが最も一般的ですが、同じワークフローがAsyncAPI、gRPCの.protoファイル、またはGraphQL SDLでも機能します。契約がテキストファイルであり、差分、ブランチ、レビューが可能である限り、それはGitネイティブです。

Gitネイティブワークフローで破壊的変更をどのように処理しますか？

破壊的変更を可視化し、意図的に行います。break/api-ブランチプレフィックスを使用し、メジャーバージョンを更新し、CODEOWNERSを通じて管理者の承認を必須とします。可能であれば、古い形式と並行して新しい形式を追加し、古いパスを期限付きで非推奨にします。PRの差分とバージョンアップを組み合わせることで、すべてのコンシューマーに破壊的変更を伝えます。

API仕様はコードと同じリポジトリに置くべきですか？

通常、1つのチームが両方を所有している場合は「はい」です。仕様と実装を同じ場所に配置すると、単一のPRで契約とハンドラを同時に変更でき、契約テストも1つのパイプラインで実行されます。多くのチームが1つの共有APIを消費し、独立したバージョン管理が必要な場合にのみ、仕様を別のリポジトリに配置します。

仕様とコードが乖離するのを防ぐにはどうすればよいですか？

CIに契約テストを追加します。これにより、実行中のサーバーに実際のリクエストが送信され、コミットされた仕様に対してすべてのレスポンスが検証されます。乖離が発生するとビルドが失敗します。仕様からスタブやクライアントを生成することと組み合わせることで、乖離は本番のバグではなく、パイプラインの失敗となります。

結論

GitネイティブAPIデザインは、製品ではなく規律です。契約をソースコードとして扱い、ブランチで進化させ、プルリクエストでレビューし、コミットされたファイルからすべてのダウンストリーム成果物を生成します。履歴、責任追跡、ロールバック、レビューは、Gitがすでに提供しているため、無料で利用できます。

小さく始めてください。仕様をリポジトリに移動し、リンティングステップを追加し、契約変更のレビューを必須とします。そこからコード生成、モック、契約テストへと発展させていきます。このワークフローは複利的に作用します。それぞれの規約が次の規約を容易にし、Git履歴はAPIがどのように成長したかの完全な記録となります。

Gitに仕様を保持するビジュアルデザインサーフェスが必要な場合は、ApidogのSpec-Firstモードを試して、双方向同期が上記のワークフローにどのように適合するかを確認してください。