APIファースト開発：フロントエンドとバックエンドの疎結合化

APIファーストとは、実装の前に、APIを使う側と提供する側で、利用場面と入力・出力・エラー・権限などの振る舞いを合意し、その後の変更も記録で管理する進め方です。使う側は、画面のほか、別のシステムとの連携や夜間の一括処理などです。合意した内容を仕様として残すと、画面と処理を並行して作りやすくなり、変更するときの影響も確かめやすくなります。

API仕様の書き方として広く使われるのがOpenAPIです。OpenAPI Specificationは、HTTP APIを記述するための、プログラミング言語に依存しない標準です（OpenAPI Specification v3.2.1、2026年9月10日公開、確認日：2026年10月21日）。Swaggerは、OpenAPIの記述を編集・表示する関連ツールの名前として使われることが多く、仕様そのものとは区別します。古い版のOpenAPIで書かれた仕様がある場合も、最新版へ移すことはAPIファーストを始める条件ではありません。

仕様を先に書く方法（Design First）と、実装から仕様を書き出す方法（Code First）は、どちらかが常に優れているわけではありません。利用側が多い、外部の会社と連携する、複数のチームで同時に作るといった場合は、先に仕様を合意する利点が大きくなります。既存の実装が多い場合は、実装から仕様を書き出し、実際の振る舞いと照らして直す方法も選べます。どちらの場合も、仕様の管理者と版を決め、仕様と実装の違いを確かめる手順を持つことが前提です。

疎結合は、責務と依存関係を整理し、決めた接点（インターフェース）を守れば、ほかの部分に影響を広げずに変更できるようにする設計です。マイクロサービス化は、機能を別のプロセスや配備の単位に分けることで、疎結合と同じ意味ではありません。1つのアプリとして配備するシステム（モノリス）でも、画面・業務処理・データの扱いを層やモジュールに分け、依存の向きを整理できます。Microsoftの解説も、層は論理的な分離であり、1つの配備単位のまま複数の層に分けることは一般的だとしています（Microsoft Learn：Common web application architectures、確認日：2026年10月21日）。

反対に、サービスを別々に分けても、ほかのサービスの内部のデータ構造や処理の順序に強く依存していれば、片方の変更がもう一方に影響します。分けたサービスの間は通信になるため、通信の失敗や遅延、監視、データの整合性、配備の手順といった負担も増えます。

そのため、何を独立して変えたいのか（画面だけを頻繁に変えたい、連携先が増える、一部の機能だけ負荷が高いなど）から、分ける範囲を決めます。バックエンドを別の言語や基盤へ書き換える場合も、APIの仕様に加えて、エラーの返し方、並び順、処理時間などの振る舞いが変わらないかを確かめます。既存システムを段階的に移す方法はレガシーシステム移行の進め方、サイト全体の構成の選び方はモダンWeb開発の構成判断で扱っています。

API仕様の確認では、入力と出力の形に加えて、誰が使うか、エラーの返し方、権限、件数や再試行の条件まで、利用側と提供側で合意します。次の表は、仕様の確認票の例です。項目ごとに確認済みと未確認を分けて記録し、APIと仕様書の版、仕様の管理者を併記します。

表は横にスクロールできます →

OpenAPIでは入力・出力・エラー・認証の方式などを記述できますが、業務上の意味（どの状態のときに何を許すか）、運用の連絡先、利用側ごとの移行の期限などは、仕様書の説明や別の記録で補います。仕様を書いたことで、実装がそのとおりに動くことや、権限の確認が行われることが保証されるわけではありません。型定義と、実行時に届くデータの検査の役割分担は、TypeScriptで保守性の高いコードを維持する記事で扱っています。

APIを変えるときは、変更の種類ごとに利用側への影響を確かめ、変更・移行・旧版の廃止を分けて合意します。必須の入力を増やす、項目を削除・改名するといった変更は、利用側の修正が必要になります。任意の項目や列挙値の追加でも、受け取る項目を厳密に検査する利用側や、未知の値を想定していない利用側には影響が出ます。GoogleのAPI設計指針（AIP-180）も、応答の列挙値を追加すると、利用側のコードが新しい値を適切に扱えない可能性があるとして注意を求めています（Google AIP-180：Backwards compatibility。Googleの設計指針で、すべてのAPIに共通の規格ではありません。確認日：2026年10月21日）。

表は横にスクロールできます →

変更は、利用側の棚卸し、影響の確認、仕様と試験の更新、連絡と移行条件の合意、段階的な反映、利用状況・エラー・利用者の確認の順で進め、旧版の廃止は合意した条件を満たしてから行います。新しい版（v2）を作れば影響がなくなるわけではなく、旧版を使う利用側の移行と、両方の版を並行して保守する負担が残ります。夜間の一括処理、更新されていない旧版のアプリ、利用者が分からない連携を残したまま、期限だけで旧版を止めません。月次の処理のように呼び出しの間隔が長い利用側もあるため、アクセスの記録に出てこないことだけで、使われていないと判断しません。

HTTPには、非推奨になったことを知らせるDeprecationヘッダー（RFC 9745）や、応答しなくなる見込みの時期を知らせるSunsetヘッダー（RFC 8594。Informationalの文書）があります。Deprecationを付けてもAPIの動作は変わらず、Sunsetの時刻も目安として扱われるため、どちらも利用側への連絡と合意の代わりにはなりません。開発や保守の会社が変わる場合は、仕様と試験の所在、連携先への連絡の担当、受入と運用の責任も引き継ぎます。契約や資料の引き継ぎ全体は、システム開発会社を変更する前の確認事項で扱っています。

次の表は、変更記録の記入例です。社内の受注API（/orders）の応答の状態（status）に、保留中を表す on_hold を加える場面を、説明のために想定しました。現在の値は new・confirmed・cancelled の3つとします。

表は横にスクロールできます →

この例では、夜間連携などの確認が残っているため公開を保留し、確認の担当と期限を決めます。既存の版で追加できるかは、利用側への影響と対応を確認して判断します。現時点では、新しい版の追加や旧版の廃止は決めていません。

BFF（Backend for Frontend）は、画面やアプリごとの要件に合わせて、データの集約や整形を担う層です。たとえば、Web画面とスマートフォンアプリで必要なデータの量や形が大きく異なる場合に、共通のAPIを画面ごとに作り替える代わりに、画面ごとのBFFで吸収します。一方で、BFFを増やすと、配備・監視・保守の対象と通信の段階が増え、応答の遅れや同じ処理の重複も起こり得ます。利用する画面が1つだけの場合や、画面ごとの要求が似ている場合は、合わないこともあります（Microsoft Learn：Backends for Frontends pattern、確認日：2026年10月21日）。

表は横にスクロールできます →

ゲートウェイは認証の確認や頻度の制限などの共通の制御、BFFは画面ごとの集約と整形、という役割の違いがあります。1つの実装が両方を担う場合もあり、すべてのシステムを「ゲートウェイ、BFF、バックエンド」の三段にする必要はありません。BFFはマイクロサービスの必須の部品でも、認証を任せれば済む層でもありません。Next.jsのサーバー側の処理やCloudflare WorkersもBFFを置く場所の候補ですが、画面の数、運用の担当、既存の基盤から選びます。

認証は「誰か」を確かめること、認可は「その人が、対象のデータ・テナント・操作を使ってよいか」を判断することです。BFFやゲートウェイで認証しても、バックエンドで対象データごとの認可を省けるわけではありません。OWASPは、公開していないREST APIでは、各エンドポイントでアクセス制御を行うこととしています（OWASP：REST Security Cheat Sheet）。また、ログインしている利用者のIDと、依頼に含まれるIDを比べるだけでは、ほかの利用者のデータへのアクセスを防ぐ対策として十分ではないとしています（OWASP API Security Top 10 2023：API1）。

BFFからバックエンドへ利用者を伝えるとき、「User-ID」のようなヘッダーを受け取っただけでは、その値を信頼できません。信頼できる伝え方には、主に次の2つがあります（OWASP：Identity Propagation Patterns、いずれも確認日：2026年10月21日）。

• トークンを渡し、受け取る側で検証する：信頼する発行元が発行したトークンを渡し、受け取るバックエンドが署名、発行元、宛先、有効期限などを検証します。検証できても、それは発行元が正しく、改ざんされていないことを示すもので、依頼された操作を許すかは別に判断します。
• 信頼するプロキシが付けたヘッダーに限る：外部から送られた同じ名前のヘッダーを入口で取り除く、プロキシ自体を認証する、プロキシを通らない直接のアクセスを防ぐ、利用者の情報を伝えてよい相手を限る、といった条件がそろう場合に限ります。

サービスの間の通信を暗号化したり、呼び出し元のサービスを認証したりしても、そのサービスが任意の利用者として振る舞ってよいことまでは保証されません。また、Cookieはブラウザでの保存と送信の仕組み、JWTはトークンの形式で、同じ分類の二択ではありません。どの画面・連携がどの方式で利用者を伝え、どこで認可を判断するかを、仕様の確認票に記録します。

APIの受入では、応答が仕様の形に合っているかと、業務の処理・権限・失敗時の動きが正しいかを分けて確かめます。OpenAPIに沿った検査は仕様との形の一致を確かめるもので、Pactのような契約テストは、利用側が実際に使うやり取りの例をもとに、提供側がそのとおりに応えるかを確かめます（Pact Docs：Introduction）。契約テストは副作用を確かめるものではなく、提供側の業務処理の正しさは別の試験で確かめる、とPactの資料も説明しています（Pact Docs：Contract tests vs functional tests、いずれも確認日：2026年10月21日）。

表は横にスクロールできます →

通信が失敗しても、依頼が処理されていないとは限りません。冪等性とは、同じ依頼を複数回送ったときのサーバーへの意図した効果が、1回だけ送った場合と同じになる性質です。応答内容やステータスまで同じになるとは限りません。HTTPの仕様では、非冪等なメソッドの依頼は、処理の意味が実際には冪等だと分かる場合や、最初の依頼が適用されていないと確認できる場合を除き、自動で再試行すべきではないとされています（RFC 9110 9.2.2、確認日：2026年10月21日）。注文の登録のような処理では、再試行してよい条件と、二重登録を防ぐ方法を合意して試験します。

OpenAPIから生成した型やクライアントは、利用側と提供側で形をそろえる助けになりますが、実行時に届くデータの検査や、業務の正しさを保証するものではありません。CIは、設定して実行した検査の範囲を毎回確かめる仕組みで、すべての不一致や互換性のない変更を防ぐものではありません。どの検査をどこで実行し、何を手作業で確かめるかを決めておきます。

導入や変更を始める前に、分かる範囲で次の点を確認します。すべてに当てはまっても、APIの品質や安全性が保証されるわけではありません。未確認の項目は、担当と確認の時期を決めて残します。

社内や外部に相談するときは、利用中の画面や連携先、変えたい内容と困っていること、仕様書や資料の所在、権限と保守の担当について、分かる範囲をまとめておくと整理を進めやすくなります。仕様書がそろっていなくても、ご相談いただけます。パスワードやAPIキー、実際の顧客データを相談フォームに書いていただく必要はありません。