前回との接続——窓口の次は「約束事」
前回のK-01で、APIをソフトウェア同士がやり取りする接点として定義しました。窓口があると分かった次は、その窓口の「約束事」を決める番です。約束事があいまいなまま作り始めると、繋いだ瞬間に噛み合いません。この講義では、エンドポイントとAPI契約という2つの言葉で、その約束事を具体的に扱えるようにします。
このスライドのポイント
- K-01で、APIをソフトウェア同士がやり取りする接点として定義した
- 窓口があると分かった次は、その窓口の約束事を決める段階
- この講義の役割: 約束事を「エンドポイント」「API契約」という2語で扱えるようにする
定義——エンドポイントとAPI契約の6要素
エンドポイントとは、APIの個々の窓口のことです。J-04で作ったルート1本、つまりメソッドとURLの組み合わせが、1つのエンドポイントにあたります。API契約とは、その窓口についてフロントとサーバーが合意しておく6つの事項です。順に、URL、メソッド、入力として何をどの形式で渡すか、出力として何が返るか、失敗したときに何番と何が返るか、そして誰が呼べるかという認証方式です。この6つが固まっていれば、フロントとサーバーは契約だけを頼りに、独立して作れます。
このスライドのポイント
- エンドポイント＝APIの個々の窓口（メソッド×URL＝J-04のルート1本ぶん）
- API契約＝その窓口についてフロントとサーバーが合意しておく6事項
- ①URL ②メソッド ③入力（何をどの形式で）④出力（何が返るか）⑤エラー（失敗時に何番と何が返るか）⑥認証方式（誰が呼べるか）
- 契約が固まれば、両側は契約だけを頼りに独立して作れる
なぜ必要か——「繋いだら動かない」の正体
この契約がないと、何が起きるでしょうか。フロントとサーバーをAIに別々に作らせたとき、入力の形式や返る値の形がずれて、繋いでも動きません。実際、「繋いだら動かない」というトラブルの大半は、この契約の不一致が原因です。逆に契約さえ先に決めておけば、片方を直しても、もう片方が巻き込まれずに済みます。
このスライドのポイント
- 契約がないと、フロントとサーバーを別々に作ったとき形式がずれて繋がらない
- 「繋いだら動かない」トラブルの大半は契約の不一致が原因
- 契約を先に決めておけば、片方を直しても、もう片方が巻き込まれない
構造——契約書をあいだに挟む
構造を、契約書のイメージで捉えます。フロントとサーバーが向き合い、その間に6項目の契約書が1枚置かれている図です。フロントは契約書を見て「この形式で送れば、この形式で返ってくる」と分かり、サーバーは「この形式で受け取り、この形式で返す」と分かります。契約が固定されていれば、両側は相手の完成を待たずに、同時並行で作業を進められます。ここが、契約を先に決める最大の利点です。
このスライドのポイント
- フロントとサーバーが向き合い、あいだに6項目の契約書が1枚置かれる構図
- フロントは「この形式で送れば、この形式で返る」と分かる
- サーバーは「この形式で受け取り、この形式で返す」と分かる
- 契約が固定なら、両側は相手の完成を待たず同時並行で作れる
契約を6項目で書き切る——経費作成の例
具体例で、契約を6項目すべて書き切ってみます。経費を新しく作るエンドポイントを考えます。URLは/api/expenses、メソッドはPOSTです。入力は金額と日付など、決めた形式でまとめて渡します。成功したときは201という番号と、作られた経費のidが返ります。失敗したときは400という番号と、その理由が返ります。認証は必要で、ログイン済みの利用者だけが呼べます。ここまで文章で決めておくと、次のスライドの表にそのまま移せます。
このスライドのポイント
- 経費を新しく作るエンドポイントを、契約6項目で書き切る
- URL: /api/expenses ／ メソッド: POST
- 入力: 金額・日付など決めた形式 ／ 成功: 201と作られた経費のid
- 失敗: 400とその理由 ／ 認証: 必要（ログイン済みの利用者のみ）
技術サンプル——契約6項目の記入表
サンプルは、いま決めた契約を6項目の表にしたものです。種別は表、目的はフロントとサーバーがずれずに作れる合意を1枚にまとめることです。読み方の要点は、入力と出力に「形式」まで書いてある点、そしてエラー欄に成功時以外の番号も並べてある点です。この表を先にAIへ渡してから実装を頼むと、両側が同じ契約を見て作るため、後で噛み合わせる手間が消えます。AIへの質問例は、「このAPIの契約を6項目の表にしてください。フロントの実装はこの契約と一致していますか」です。
このスライドのポイント
- 種別: table
- 目的: フロントとサーバーがずれずに作れる合意を1枚にまとめる
- サンプル本体:
混同しやすい概念——エンドポイントとAPI
混同しやすいのが、エンドポイントとAPIの関係です。エンドポイントは窓口が1つ、たとえば経費を作る窓口1本を指します。一方でAPIは、その窓口の集まりや、やり取りの仕組み全体を指す、より大きい言葉です。1つのAPIの中に、経費を作る、一覧を取る、削除するといった複数のエンドポイントが並んでいる、という関係です。
このスライドのポイント
- エンドポイント＝窓口が1つ（例: 経費を作る窓口1本）
- API＝窓口の集まりや、やり取りの仕組み全体を指す大きい言葉
- 1つのAPIの中に、作る・一覧を取る・削除するなど複数のエンドポイントが並ぶ
バイブコーディングでの確認点——契約を先に出させる
バイブコーディングでの確認点です。機能を追加するたびに、いきなりコードを書かせるのではなく、まず契約を6項目の表で出させ、人間が確認してから実装させる、という順序を守ってください。これは、A-08で学んだ「生成の前に決める」という原則の、API版にあたります。AIへの質問例は、「新しく足すこの機能のエンドポイント契約を、6項目の表で先に出してください。実装はそのあとでお願いします」です。
このスライドのポイント
- 機能追加のたびに、いきなり実装させず「契約を6項目の表で先に出させる」
- 人間が表を確認してから実装させる順序を守る
- これはA-08「生成の前に決める」の、API版
まとめと一問一答
最後に一問一答です。API契約の6要素は何でしょうか。（間）答えは、URL、メソッド、入力、出力、エラー、認証方式の6つです。30秒でまとめます。エンドポイントはAPIの窓口1本、API契約はその窓口の6つの約束事で、契約を先に固めればフロントとサーバーは独立して作れます。次回のK-03では、この契約をどう設計するかの流儀であるRESTへ進みます。関連資料は「API連携 超入門」「PRD簡易テンプレート」です。
このスライドのポイント
- 一問一答: 「API契約の6要素は？」→ URL・メソッド・入力・出力・エラー・認証方式
- 30秒まとめ: エンドポイントは窓口1本、API契約はその6つの約束事。先に固めれば両側を独立して作れる
- 次回: K-03、契約の設計流儀であるRESTへ
- 関連資料: 「API連携 超入門」「PRD簡易テンプレート」
