第11章 APIで画面と業務をつなぐ | エンジニア入門研修

この章では、第9章のユースケースと第10章のDB設計を、画面から呼び出せるAPI契約へ変える。ここで登場する用語は、Web開発の現場でそのまま使う一般的な技術・実務用語である。意味と読み方、そして「どこで何を確認するか」をあわせて身につけておく。

API

読み：エーピーアイ（Application Programming Interface）
一言で言うと：画面や他のプログラムが、業務上の操作を安全に依頼するための約束。
くわしく：APIは、バックエンドにあるURLの一覧ではない。どのURLへ、どのmethodで、何を送り、何が返り、失敗したときにどう分かるのかを決めた取り決めである。さらに、誰がその操作をしてよいか、どの入力を受け付けるか、DBの制約違反をどうエラーへ変えるかまで含む。これを実装前に書いておくと、フロントエンド、バックエンド、テスト、レビューが同じ前提で進められる。第5章では「外部から呼べる入口」として軽く触れたが、本章ではその契約を設計する側に立つ。
具体例：支援ステータス機能では、担当受講者一覧を取得する GET /api/mentor/learners と、支援ステータスを更新する PATCH /api/mentor/learners/{learnerId}/support-status の二つがAPIになる。
つまずきやすい点：APIをURLの集まりだと思い込むと、認可やエラー、入力検証など「約束として決めるべきこと」が後付けになりやすい。
関連語：HTTP JSON API（第11章）、endpoint（第11章）、API（第5章）
テキスト本文での登場箇所：第11章「APIは、画面と業務ルールとDBの境界である」

HTTP JSON API

読み：エイチティーティーピージェイソンエーピーアイ（HTTP JSON API）
一言で言うと：HTTPで通信し、データをJSON形式でやり取りするAPIの形。
くわしく：HTTP JSON APIは、requestとresponseの本文（body）をJSONで表すAPIである。多くのWebアプリが採用する一般的な形で、フロントエンドとバックエンドの両方がJSONを読み書きできる。本章はこの形を前提にし、特定のフレームワークの書き方には踏み込まない。HTTPやJSONそのものは第7章で扱った前提知識である。
具体例：支援ステータス更新では {"status":"needs_support","note":"..."} というJSONをbodyで送り、{"learnerId":1,"supportStatus":"needs_support",...} というJSONが返る。
つまずきやすい点：bodyをJSONで送るときは Content-Type: application/json を付け忘れない。付けないとサーバーがJSONとして読めないことがある。
関連語：JSON（第7章）、HTTP（第7章）、body（第11章）、API（第11章）
テキスト本文での登場箇所：第11章導入、第11章「APIは、画面と業務ルールとDBの境界である」

REST

読み：レスト（REST／Representational State Transfer）
一言で言うと：HTTPのmethodとURLを使って、対象（リソース）への操作を表すAPI設計の考え方。
くわしく：RESTは、URLで「対象」を、HTTP methodで「その対象に何をするか」を表す設計スタイルである。本章で GET を取得、PATCH を一部更新に使い分けるのは、この考え方に沿っている。ただし本章は、テーブルへのCRUDをそのままURLにするのではなく、ユースケースからendpointを決めることを勧めている。RESTの形に寄せすぎて業務上の操作や権限が見えなくならないよう注意する。
具体例：支援ステータス機能で PATCH /api/mentor/learners/{learnerId}/support-status は、受講者という対象の支援ステータスを一部更新する、というRESTらしい読み方ができる。
つまずきやすい点：PATCH /api/learner_support_statuses/{id} のようにテーブル名をそのままURLにすると、形はRESTでも、誰が何のために更新するのかが読み取りにくくなる。
関連語：endpoint（第11章）、method（第7章）、CRUD（第11章）
テキスト本文での登場箇所：第11章「ユースケースからendpointを決める」

endpoint

読み：エンドポイント（endpoint）
一言で言うと：APIの入口。methodとpathの組で、何を依頼できるかを表す。
くわしく：endpointは、URLの形だけではなく、HTTP methodと組み合わせて何ができるかを示す。同じpathでも、GET なら取得、PATCH なら更新と意味が変わる。endpointはテーブル名からではなく、ユースケースから決めるとよい。そうすると、誰が何のために呼ぶのかがpathから読み取りやすくなる。
具体例：支援ステータス機能では、GET /api/mentor/learners が担当受講者一覧の取得endpoint、PATCH /api/mentor/learners/{learnerId}/support-status が支援ステータス更新のendpointになる。
つまずきやすい点：pathが同じでもmethodが違えば別のendpointである。URLだけ見て同じ操作だと思い込まない。
関連語：method（第7章）、path params（第11章）、REST（第11章）、API（第11章）
テキスト本文での登場箇所：第11章「ユースケースからendpointを決める」

HTTP method

読み：エイチティーティーピーメソッド（HTTP method）
一言で言うと：requestで「何をしたいか」を示す動詞のような指定。→第7章
くわしく：methodの基本（GET、POST、PATCH、PUT、DELETE）は第7章で扱った。本章では、ユースケースに合わせてどれを選ぶかに重点を置く。取得は GET、新規作成や処理依頼は POST、既存の一部更新は PATCH、対象全体の置き換えは PUT、削除は DELETE と読む。支援ステータスのように「受講者に紐づく一部だけ」を変えるなら、対象を作り直す PUT より、一部更新の PATCH が読みやすい。
具体例：支援ステータス機能では、一覧取得に GET、支援ステータスの部分更新に PATCH を選ぶ。
つまずきやすい点：「更新」と聞くと PUT を選びがちだが、一部だけ変えるなら PATCH が意図を正しく伝える。
関連語：method（第7章）、endpoint（第11章）、PATCH（第7章）、PUT（第7章）
テキスト本文での登場箇所：第11章「HTTP methodとstatus codeは、操作の意図と結果を伝える」

HTTP status code

読み：エイチティーティーピーステータスコード（HTTP status code）
一言で言うと：responseで処理結果の種類を示す3桁の数字。→第7章（概念）
くわしく：status codeの意味の体系（200番台＝成功、400番台＝呼び出し側に近い問題、500番台＝サーバー側で調べる問題）は第7章で扱った。本章では、APIでどう使い分けるかに絞る。成功時には作成なら 201、取得・更新の成功なら 200 を返す。失敗時は、requestの形が不正なら 400、未ログインなら 401、許可されない操作なら 403、対象がないなら 404、形は読めるが業務上受け付けられない値なら 422、サーバー側の想定外なら 500 を返す。ただしstatus codeだけでは「どの項目がなぜ不正か」が伝わらないため、error responseとセットで決める。
具体例：支援ステータス更新で、status が許可外なら 400 または 422、未ログインなら 401、担当外メンターなら 403、存在しない受講者なら 404、更新成功なら 200 を返す、と契約に書く。
つまずきやすい点：何でも 500 で返すと呼び出し元が何も判断できない。失敗の種類ごとにstatus codeを分けて返す。
関連語：status code（第7章）、error response（第11章）、400 Bad Request（第11章）、404 Not Found（第11章）、500 Internal Server Error（第11章）
テキスト本文での登場箇所：第11章「HTTP methodとstatus codeは、操作の意図と結果を伝える」「error responseは、失敗時の契約である」

200 OK

読み：にひゃくオーケー（200 OK）
一言で言うと：取得や更新などの処理が成功したことを示す代表的な成功status code。
くわしく：200 は、requestが正しく処理できたときに返す、もっとも基本的な成功コードである。本章では、取得（GET）や更新（PATCH）の成功で返す。成功時には、success responseとして画面が使える値もあわせて返す。逆に、本来失敗すべき操作で 200 が返ってしまうと、重大な不具合の兆候になる。新規作成の成功を区別したいときは 201 を使う設計もあるが、本章の支援ステータス更新は更新なので 200 を使う。
具体例：支援ステータス更新が成功すると 200 と更新後のJSONが返る。一方、担当外メンターのrequestで 200 が返って更新できてしまうなら、認可の重大な不具合である。
つまずきやすい点：失敗すべき操作が 200 で通っていないかを必ず確認する。成功コードが返るからといって正しいとは限らない。
関連語：HTTP status code（第11章）、success response（第11章）、403 Forbidden（第11章）
テキスト本文での登場箇所：第11章「HTTP methodとstatus codeは、操作の意図と結果を伝える」「curlで、画面がなくてもAPIを確認する」

400 Bad Request

読み：よんひゃくバッドリクエスト（400 Bad Request）
一言で言うと：JSONの形、型、必須項目など、request全体が不正なことを示す。
くわしく：400 は、サーバーがrequestを読もうとしても、形式として受け付けられないときに返す。bodyがJSONとして壊れている、必須の項目がない、型が違う、といった「外から来た値の形の問題」が対象である。入力検証で弾く典型的な失敗である。利用者側で直せる問題なので、400番台に分類される。
具体例：支援ステータス更新で、bodyのJSONが壊れていたり status が文字列でなかったりすると 400 を返す。
つまずきやすい点：「形は読めるが業務上ダメな値」は 422 の領域で、400 と使い分ける方針のチームもある。どちらに寄せるかを契約で先に決める。
関連語：HTTP status code（第11章）、入力検証（第11章）、422 Unprocessable Content（第11章）
テキスト本文での登場箇所：第11章「error responseは、失敗時の契約である」

401 Unauthorized

読み：よんひゃくいちアンオーソライズド（401 Unauthorized）
一言で言うと：ログインしていない、または認証情報が無効なことを示す。
くわしく：401 は、呼び出し元が誰なのかを確認できないときに返す。ログインしていない、トークンが期限切れ、認証情報が間違っている、といった「認証」の失敗である。名前に Unauthorized とあるが、扱うのは認可ではなく認証であることに注意する。許可の問題は 403 で表す。
具体例：支援ステータス更新APIを、トークンを付けずに呼ぶと 401 が返る。
つまずきやすい点：名称は「Unauthorized（権限なし）」だが、実際は認証の失敗を表す。認可不足の 403 と取り違えやすい。
関連語：HTTP status code（第11章）、認証（第11章）、403 Forbidden（第11章）
テキスト本文での登場箇所：第11章「error responseは、失敗時の契約である」

403 Forbidden

読み：よんひゃくさんフォービドゥン（403 Forbidden）
一言で言うと：認証はできているが、その操作は許可されないことを示す。
くわしく：403 は、誰かは分かっているが、その人にはその操作の権限がないときに返す。認可の失敗を表す。ログイン済みであることは、どの受講者でも更新してよいことを意味しない。支援ステータス機能では、担当外の受講者を更新しようとしたときの典型的な応答になる。
具体例：別メンターのトークンで PATCH /api/mentor/learners/1/support-status を呼ぶと、担当外なので 403 と FORBIDDEN を返すのが期待値である。もし 200 で更新できてしまうなら認可の重大な不具合である。
つまずきやすい点：未ログインの 401 と、権限不足の 403 を混同しない。前者は「誰か分からない」、後者は「誰かは分かるが許可されない」。
関連語：HTTP status code（第11章）、認可（第11章）、401 Unauthorized（第11章）
テキスト本文での登場箇所：第11章「error responseは、失敗時の契約である」「curlで、画面がなくてもAPIを確認する」

404 Not Found

読み：よんひゃくよんノットファウンド（404 Not Found）
一言で言うと：対象が存在しない、または存在を見せない方針で隠すことを示す。
くわしく：404 は、指定した対象が見つからないときに返す。pathの綴り間違いや、存在しないIDの指定で起きる。さらに、存在を相手に知られたくない場合、本当は 403 でも 404 を返して存在自体を隠す方針もある。どう扱うかはチームのエラー方針で先に決める。
具体例：支援ステータス更新で、存在しない受講者ID（例: 9999）を指定すると 404 を返す。
つまずきやすい点：「担当外だから隠したい」場合に 404 を使うか、403 を返すかは設計判断であり、暗黙に決めない。
関連語：HTTP status code（第11章）、path params（第11章）、403 Forbidden（第11章）
テキスト本文での登場箇所：第11章「error responseは、失敗時の契約である」

422 Unprocessable Content

読み：よんひゃくにじゅうにアンプロセッサブルコンテント（422 Unprocessable Content）
一言で言うと：形式は読めるが、業務上は受け付けられない値であることを示す。
くわしく：422 は、JSON自体は正しく型も合っているが、業務ルールから見て受け付けられない値のときに返す。「形の問題」の 400 と、「内容の問題」の 422 を分けたいときに使う。許可されていない支援ステータスの値などが対象になりうる。400 と 422 のどちらに寄せるかはチームの方針で統一する。
具体例：支援ステータス更新で、JSONは正しいが status に未定義の urgent が入っているとき、422 を返す設計が考えられる。
つまずきやすい点：400 と 422 の境界は曖昧になりやすい。どの失敗をどちらにするかを、API契約として先に決める。
関連語：HTTP status code（第11章）、入力検証（第11章）、400 Bad Request（第11章）
テキスト本文での登場箇所：第11章「error responseは、失敗時の契約である」

500 Internal Server Error

読み：ごひゃくインターナルサーバーエラー（500 Internal Server Error）
一言で言うと：サーバー側で起きた想定外の問題を示す。
くわしく：500 は、サーバー内部で予期しないエラーが起きたときに返す。500番台はサーバー側で調査すべき問題の手がかりになる。ただし、本来は 400 や 403 で表せる失敗まで 500 にまとめると、呼び出し元は何も判断できなくなる。また、内部のstack traceをそのままresponseに返すと、ファイルパスやSQL、秘密情報に近い情報が漏れる危険がある。
具体例：支援ステータス更新で、担当外メンターのrequestが 500 になるなら、本来 403 へ変換すべきエラー処理が足りない可能性がある。
つまずきやすい点：何でも 500 にしない。利用者側で直せる失敗は400番台へ正しく変換する。
関連語：HTTP status code（第11章）、error response（第11章）、スタックトレース（第8章）
テキスト本文での登場箇所：第11章「error responseは、失敗時の契約である」

request

読み：リクエスト（request）
一言で言うと：画面やプログラムからサーバーへ送る依頼。→第7章
くわしく：requestの基本は第7章で扱った。本章では、requestをひとまとまりの入力として見るのではなく、path params、query params、headers、bodyの四つの場所に分けて意味を考える。どこに何を入れるかで役割が変わるからである。さらに重要なのは、bodyの値をすべて信用しないことである。利用者はrequestを書き換えられるので、現在のメンターはbodyではなくサーバー側で確認した情報から決める。
具体例：支援ステータス更新のrequestは、対象を learnerId（path params）で、本文を status と note（body）で、認証情報をheadersで送る。bodyに mentorId が入っていても、それを現在のメンターとして使ってはいけない。
つまずきやすい点：bodyに入っている mentorId のような値をそのまま信用すると、なりすましを許してしまう。
関連語：request（第7章）、path params / query params / headers / body（第11章）、認証（第11章）
テキスト本文での登場箇所：第11章「requestは、場所ごとに意味を分ける」

response

読み：レスポンス（response）
一言で言うと：サーバーがrequestへ返す返事。→第7章
くわしく：responseの基本は第7章で扱った。本章では、DBの行をそのまま返すのではなく、画面が次の表示や状態更新に使いやすい形へ整えることを重視する。DBのカラム名（例: note、updated_at）を、画面側の命名（例: supportNote、updatedAt）へ変えてよい。ただし、画面に必要な値を削りすぎないこと、null・空文字・未設定・初期値の扱いを曖昧にしないことに注意する。
具体例：支援ステータス更新後のresponseは {"learnerId":1,"supportStatus":"needs_support","supportNote":"...","updatedAt":"..."} のように、画面が再表示に使える値を整えて返す。
つまずきやすい点：DBの内部都合（テーブル名や保存上の名前）をそのまま出すと、画面がDB構造に引きずられる。
関連語：response（第7章）、success response / error response（第11章）、body（第11章）
テキスト本文での登場箇所：第11章「responseは、画面が扱いやすい形で設計する」

path params

読み：パスパラメータ（path parameters）
一言で言うと：URLの一部として、操作の対象を指定する値。
くわしく：path paramsは、/api/mentor/learners/{learnerId}/support-status の {learnerId} のように、URLの一部に埋め込んで「どの対象か」を表す。一覧の中から特定の一件を指すときに使う。query paramsが「絞り込み条件」を表すのに対し、path paramsは「対象そのもの」を指す、という役割の違いがある。
具体例：支援ステータス更新で、受講者ID 1 を更新するときは PATCH /api/mentor/learners/1/support-status のように、1 がpath paramsになる。
つまずきやすい点：対象の指定（path params）と絞り込み条件（query params）を取り違えやすい。対象はpath、条件はqueryと覚える。
関連語：query params（第11章）、endpoint（第11章）、path（第7章）
テキスト本文での登場箇所：第11章「requestは、場所ごとに意味を分ける」

query params

読み：クエリパラメータ（query parameters）
一言で言うと：URLの ? の後ろに置く、絞り込みや検索などの条件。
くわしく：query paramsは、?supportStatus=needs_support のように ? 以降に 名前=値 の形で付ける。一覧の絞り込みや並び替えなど、対象を限定する条件に使う。任意項目にすることが多く、付けなければ全件、付ければ絞り込み、という設計ができる。第7章の query string と同じ仕組みを、API設計の語彙で呼んだものである。
具体例：支援ステータス一覧を要支援の受講者だけに絞るときは GET /api/mentor/learners?supportStatus=needs_support のように supportStatus をquery paramsで送る。
つまずきやすい点：対象を指すpath paramsと条件を表すquery paramsを混同しない。「どれを」はpath、「どんな条件で」はquery。
関連語：path params（第11章）、query string（第7章）、入力検証（第11章）
テキスト本文での登場箇所：第11章「requestは、場所ごとに意味を分ける」

headers

読み：ヘッダー（headers）
一言で言うと：requestやresponseに付く追加情報。→第7章
くわしく：headersの基本は第7章で扱った。本章では、APIを呼ぶときに付ける代表的なheaderとして、bodyの形式を示す Content-Type: application/json と、認証情報を運ぶheader（例: Authorization）を扱う。認証情報やCookieはheadersに関係する。bodyやpathとは別の場所に、通信の付帯情報を載せるのがheadersである。
具体例：支援ステータス更新では Content-Type: application/json と Authorization: Bearer <token> をheadersに付けて送る。
つまずきやすい点：JSONをbodyで送るのに Content-Type: application/json を付け忘れると、サーバーがbodyを正しく読めないことがある。
関連語：headers（第7章）、body（第11章）、Content-Type（第11章）、認証（第11章）
テキスト本文での登場箇所：第11章「requestは、場所ごとに意味を分ける」

body

読み：ボディ（body）
一言で言うと：作成や更新で送る、requestやresponseの本文。→第7章
くわしく：bodyの基本は第7章で扱った。本章のHTTP JSON APIでは、bodyにJSONを入れて送受信する。作成・更新のrequestでは、変更したい値をbodyに入れる。重要なのは、request bodyの値をすべて信用してはいけないことである。利用者はbodyを自由に書き換えられるので、認証や認可に関わる情報はbodyから取らず、サーバー側で確認した情報を使う。
具体例：支援ステータス更新のrequest bodyは {"status":"needs_support","note":"学習ログの提出が遅れている"} で、status と note を送る。bodyに mentorId を入れても、それを操作者として信用しない。
つまずきやすい点：bodyに来た値を検証せず、または信用しすぎて使うと、不正な値やなりすましを通してしまう。
関連語：body（第7章）、request（第11章）、入力検証（第11章）、認証（第11章）
テキスト本文での登場箇所：第11章「requestは、場所ごとに意味を分ける」

success response

読み：サクセスレスポンス（success response）
一言で言うと：処理が成功したときに返すresponseの中身。
くわしく：success responseは、200番台のstatus codeとともに返す、成功時の本文である。API契約では、成功時にどんなJSONを返すかを実装前に決める。画面はこの値を使って次の表示や状態更新を行うので、必要な値を過不足なく含める。更新系では、更新後の最新値（新しいstatus、更新日時、メモなど）を返すと、画面が再取得せずに表示を更新できる。
具体例：支援ステータス更新のsuccess responseは {"learnerId":1,"supportStatus":"needs_support","supportNote":"...","updatedAt":"..."} のように、更新後の値をまとめて返す。
つまずきやすい点：成功したことだけ返して中身を省くと、画面が再取得を強いられる。更新後の値を含めると扱いやすい。
関連語：response（第11章）、error response（第11章）、200 OK（第11章）
テキスト本文での登場箇所：第11章「API契約を書く」

error response

読み：エラーレスポンス（error response）
一言で言うと：失敗したときに、次の判断材料を返すための契約。
くわしく：error responseは、実装の最後に付ける飾りではなく、失敗時に画面・利用者・開発者が次に何を判断できるかを決める契約である。status codeだけでは「どの項目がなぜ失敗したか」が伝わらないため、本文に情報を入れる。開発者向けの code（機械が判定しやすい識別子）と、利用者や画面向けの message（読める説明）を分ける。入力エラーでは、どの項目がなぜ失敗したかを fields に入れると、画面がフォームの近くにエラーを表示しやすい。stack traceをそのまま返すのは情報漏えいの危険があるため避ける。
具体例：支援ステータスの値が不正なとき {"code":"INVALID_SUPPORT_STATUS","message":"支援ステータスの値が正しくありません。","fields":{"status":"none, needs_support, in_progress, resolved のいずれかを指定してください。"}} のように返す。
つまずきやすい点：status codeだけ返して本文を省くと、呼び出し元は原因を特定できない。code と message を分けて入れる。
関連語：success response（第11章）、HTTP status code（第11章）、入力検証（第11章）
テキスト本文での登場箇所：第11章「error responseは、失敗時の契約である」

認証

読み：にんしょう（authentication／authn）
一言で言うと：呼び出し元が「誰か」を確認すること。
くわしく：認証は、requestを送ってきたのが誰なのかを確かめる。ログインしているか、トークンやセッションが有効かを見る。認証に失敗したら、通常 401 を返す。認証は「誰か」を確かめるだけで、「その人が何をしてよいか」までは決めない。そこは認可の役割である。現在の利用者は、書き換えられるrequest bodyからではなく、認証で確認した情報から決める。第14章でも改めて扱う。
具体例：支援ステータス更新APIで、Authorization headerのトークンが有効かを確認し、ログイン中のメンターを特定するのが認証である。トークンがなければ 401。
つまずきやすい点：認証（誰か）と認可（してよいか）を混同しやすい。ログイン済みでも、担当外の受講者を更新してよいわけではない。
関連語：認可（第11章）、401 Unauthorized（第11章）、headers（第11章）、Cookie（第7章）
テキスト本文での登場箇所：第11章「入力検証、認証、認可、業務ルール、DB制約を分ける」

認可

読み：にんか（authorization／authz）
一言で言うと：その人がその操作をしてよいかを確認すること。
くわしく：認可は、認証で「誰か」が分かった上で、その人にその操作の権限があるかを確かめる。支援ステータス機能では、ログイン中のメンターが対象受講者を担当しているかを見る。ログイン済みであることは、担当外の受講者を更新してよいことを意味しない。認可に失敗したら、通常 403 を返す。担当外更新はDB制約だけでは守りにくいため、API側の認可で確認する必要がある。第14章でも改めて扱う。
具体例：支援ステータス更新で、ログイン中のメンターが対象受講者の担当かを mentor_assignments で確認するのが認可である。担当外なら 403 と FORBIDDEN。
つまずきやすい点：認証が通れば認可も通ると思い込みやすい。両者は別の確認で、認可は対象ごとに判定する。
関連語：認証（第11章）、403 Forbidden（第11章）、use case（第11章）、業務ルール（第11章）
テキスト本文での登場箇所：第11章「入力検証、認証、認可、業務ルール、DB制約を分ける」

入力検証

読み：にゅうりょくけんしょう（input validation）
一言で言うと：外から来た値の形が正しいかを確認すること。
くわしく：入力検証は、requestで届いた値が、期待した形・型・範囲かを確かめる。learnerId が数値として扱えるか、status が許可された値か、note が最大文字数を超えていないか、JSONの形が壊れていないか、などを見る。入力検証は「値の形」を見る点で、「誰か」を見る認証、「してよいか」を見る認可とは別である。形が不正なら通常 400、形は読めるが業務上ダメなら 422 で返す。第14章でも改めて扱う。
具体例：支援ステータス更新で、bodyの status が none, needs_support, in_progress, resolved のいずれかかを確認し、外れていれば入力エラーとして返すのが入力検証である。
つまずきやすい点：入力検証・認証・認可・業務ルール・DB制約を一つのif文の山に混ぜると、どこで何を直すべきか見えなくなる。欄を分けて整理する。
関連語：認証（第11章）、認可（第11章）、業務ルール（第11章）、400 Bad Request（第11章）、422 Unprocessable Content（第11章）
テキスト本文での登場箇所：第11章「入力検証、認証、認可、業務ルール、DB制約を分ける」

業務ルール

読み：ぎょうむルール（business rule）
一言で言うと：仕事上の決まりごと。アプリが守るべきドメインの約束。
くわしく：業務ルールは、仕様や運用で決まっている仕事上の決まりである。技術的な制約ではなく、何が正しい運用かを表す。入力検証（値の形）やDB制約（保存の防衛線）とは別の層で、何を許し何を許さないかをドメインの言葉で決める。実装前に明文化しておくと、認可や入力検証の判断基準になる。
具体例：支援ステータス機能の業務ルールには「支援ステータスはメンターが手動で変更する」「初回リリースでは自動アラートは作らない」「候補値は none, needs_support, in_progress, resolved である」などがある。
つまずきやすい点：業務ルールをDB制約や入力検証と同一視しない。技術で守る部分と、業務として決める部分は分けて記録する。
関連語：認可（第11章）、入力検証（第11章）、use case（第11章）、制約（第10章）
テキスト本文での登場箇所：第11章「入力検証、認証、認可、業務ルール、DB制約を分ける」

handler

読み：ハンドラー（handler）
一言で言うと：HTTP requestを受け取り、responseへ変換するAPIの入口の処理。
くわしく：handlerは、route（URLとhandlerの対応づけ）から呼ばれ、HTTPの入口として path params、query params、headers、body を読む。ただし、入力検証・認証・認可・業務処理・DBアクセス・エラー変換をすべて一つのhandlerに詰め込むと、処理の意図が読みにくくなる。そこで、業務判断は use case へ、DB読み書きは repository へ委ね、handlerはHTTPと業務の橋渡しに絞る。こうすると、不具合の種類ごとに読む場所を絞れる。
具体例：支援ステータス更新のhandlerは、learnerId をpathから読み、bodyの status・note を読んで検証し、現在の利用者を取得してから use case を呼び、結果をresponseへ整える。
つまずきやすい点：handlerに全部を書くと、認可の不具合かSQLの不具合かを切り分けにくくなる。役割で分ける。
関連語：route（第11章）、use case（第11章）、repository（第11章）、レイヤード設計（第11章）
テキスト本文での登場箇所：第11章「handlerに全部を書かない」

route

読み：ルート（route）
一言で言うと：URLとmethodの組を、どのhandlerが処理するか対応づける設定。
くわしく：routeは、「このmethodでこのpathに来たら、このhandlerを呼ぶ」という対応づけ（ルーティング）である。requestはまずrouteで振り分けられ、対応するhandlerに渡る。routeとhandlerはAPIの入口の段階であり、その先で use case や repository に処理を委ねる。
具体例：支援ステータス機能では、PATCH /api/mentor/learners/{learnerId}/support-status というrouteが、支援ステータス更新のhandlerに対応づけられる。
つまずきやすい点：routeはあくまで振り分けで、業務判断やDBアクセスはそこに書かない。役割をhandlerより先に詰め込まない。
関連語：handler（第11章）、endpoint（第11章）、path（第7章）
テキスト本文での登場箇所：第11章「handlerに全部を書かない」

use case

読み：ユースケース（use case）
一言で言うと：業務上の操作を実現する処理のまとまり。業務判断を担当する層。
くわしく：use caseは、HTTPの細部やSQLの細部から離れて、「業務として何をするか」を扱う。支援ステータス更新なら、メンターがその受講者の担当か（認可）、業務ルールに沿うかを判断し、必要な更新を repository に依頼する。第9章で扱った「ユースケース＝利用者が達成したいこと」を、実装上の処理のまとまりとして表したものである。認可の不具合なら、まずここを読む。
具体例：支援ステータス更新の use case は、メンターのrole確認、担当関係の確認、支援ステータスの更新依頼、という業務の流れを担う。
つまずきやすい点：use caseにHTTPのstatus codeやSQL文を直接書くと、層の役割が崩れる。業務判断に絞る。
関連語：handler（第11章）、repository（第11章）、認可（第11章）、業務ルール（第11章）、ユースケース（第9章）
テキスト本文での登場箇所：第11章「handlerに全部を書かない」

repository

読み：リポジトリ（repository）
一言で言うと：DBへの読み書きを担当する部品。データアクセスを一か所にまとめる。
くわしく：本章のrepositoryは、いわゆるリポジトリパターンの repository で、DBアクセス（SELECT、INSERT、UPDATEなど）を担当する層である。use caseはrepositoryに「担当関係を読む」「支援ステータスをupsertする」と依頼し、SQLの細部はrepositoryに閉じ込める。こうすると、SQLの不具合はrepositoryを読めばよい、と読む場所を絞れる。なお、これは第6章で扱ったgitの「リポジトリ（コードの保管場所）」とは別の概念で、同じ単語が違う意味で使われている点に注意する。
具体例：支援ステータス更新では、repositoryが mentor_assignments を読んで担当関係を確認し、learner_support_statuses をupsertする、というDBアクセスを担う。
つまずきやすい点：第6章のgitリポジトリ（コードの保管場所）と混同しやすい。本章のrepositoryはDBアクセスを担う部品である。
関連語：handler（第11章）、use case（第11章）、レイヤード設計（第11章）、repository（第6章、別概念）
テキスト本文での登場箇所：第11章「handlerに全部を書かない」

レイヤード設計

読み：レイヤードせっけい（layered architecture）
一言で言うと：処理を役割ごとの層に分けて、読む場所を絞れるようにする設計。
くわしく：レイヤード設計は、HTTPの入口（route・handler）、業務判断（use case）、DBアクセス（repository）のように、処理を役割ごとの層に分ける考え方である。本章では「handlerに全部を書かない」として、この分け方を勧めている。これは抽象化のための抽象化ではなく、不具合の種類ごとに読む場所を絞り、チーム開発での保守性を上げるための実用的な分担である。
具体例：支援ステータス更新で、認可の不具合なら use case、SQLの不具合なら repository、responseの形が画面と合わないなら handler、と層をたどって読む場所を決められる。
つまずきやすい点：層を分けること自体が目的化しないようにする。読む場所を絞れて初めて意味がある。
関連語：handler（第11章）、use case（第11章）、repository（第11章）
テキスト本文での登場箇所：第11章「handlerに全部を書かない」

CRUD

読み：クラッド（CRUD／Create, Read, Update, Delete）
一言で言うと：データに対する作成・取得・更新・削除という四つの基本操作。
くわしく：CRUDは、Create（作成）、Read（取得）、Update（更新）、Delete（削除）の頭文字で、データの基本操作をまとめた言い方である。多くのAPIはこれに対応するが、本章は「テーブルへのCRUDをそのままendpointにすると、認可や業務ルールが後付けになりやすい」と注意している。初学者は、CRUDの形から入る前に、ユースケースからendpointを考えるほうがよい。
具体例：支援ステータス機能を learner_support_statuses テーブルへのCRUDだけで設計すると、「担当受講者だけ更新できる」という認可がpathから見えなくなる。
つまずきやすい点：CRUDに急ぐと、業務上の操作や権限がendpointから読み取れなくなる。ユースケースを先に置く。
関連語：endpoint（第11章）、REST（第11章）、method（第7章）
テキスト本文での登場箇所：第11章「ユースケースからendpointを決める」

Content-Type

読み：コンテントタイプ（Content-Type）
一言で言うと：bodyの中身がどんな形式かを示すheader。
くわしく：Content-Typeは、request/responseのbodyがどの形式（メディアタイプ）かを示すheaderである。JSONを送るなら application/json を指定する。サーバーはこの値を見てbodyの読み方を決めるため、JSONを送るのにContent-Typeを付けないと、正しく解釈されないことがある。HTTP JSON APIでは、bodyを送るrequestに付ける基本のheaderである。
具体例：支援ステータス更新では Content-Type: application/json を付けて、bodyがJSONであることをサーバーに伝える。
つまずきやすい点：bodyにJSONを入れているのにContent-Typeを忘れると、サーバーがbodyを読めず 400 になることがある。
関連語：headers（第11章）、body（第11章）、HTTP JSON API（第11章）
テキスト本文での登場箇所：第11章「requestは、場所ごとに意味を分ける」

トランザクション

読み：トランザクション（transaction）
一言で言うと：複数のDB更新を、まとめて成功させるかまとめて失敗させる仕組み。
くわしく：トランザクションは、複数のDB操作を一体として扱い、全部成功か全部失敗かのどちらかにする仕組みである。途中まで成功して途中で失敗した、という中途半端な状態を防ぐ。本章では、支援ステータスの履歴も保存する設計に進むと、現在値の更新と履歴行の追加をひとまとまりにしたくなる、という文脈で出てくる。API設計の段階では実装コードは書かなくてよいが、どこで一体性が必要になるかを、API設計のメモに残す。
具体例：支援ステータスの履歴も持つ設計なら、learner_support_statuses の更新と support_status_history への追加を一つのトランザクションで行い、片方だけ反映される事態を防ぐ。
つまずきやすい点：現在値だけの単純な更新ではトランザクションを意識しなくても済むことがあり、履歴を足したときに必要性を見落としやすい。
関連語：repository（第11章）、use case（第11章）
テキスト本文での登場箇所：第11章「トランザクションが必要になる場合を説明する」

curl

読み：カール（curl）
一言で言うと：ターミナルからHTTP requestを送るコマンド。→第5章
くわしく：curlの基本は第5章で扱った。本章では、画面が完成していなくても、API契約どおりにrequestを送ってstatus codeとresponse bodyを確認する道具として使う。-i はresponse headersも表示し、-X はmethodを指定し、-H はheadersを、-d はrequest bodyを指定する。正常系だけでなく、入力不正・未ログイン・権限なし・対象なしといった異常系も確認できる。確認結果は記録に残し、テストやPR説明の材料にする。
具体例：支援ステータス更新を curl -i -X PATCH -H "Content-Type: application/json" -H "Authorization: Bearer <token>" -d '{"status":"needs_support","note":"..."}' "http://localhost:3000/api/mentor/learners/1/support-status" で確認する。担当外メンターのトークンで呼べば 403 が返ることも確かめる。
つまずきやすい点：実行していないcurlやSQLを「確認済み」として書かない。実際に動かした結果だけを残す。
関連語：curl（第5章）、HTTP status code（第11章）、error response（第11章）、headers（第11章）
テキスト本文での登場箇所：第11章「curlで、画面がなくてもAPIを確認する」

OpenAPI

読み：オープンエーピーアイ（OpenAPI）
一言で言うと：HTTP APIの仕様を機械にも読める形で書くための標準フォーマット。
くわしく：OpenAPIは、endpoint、method、request、response、status codeなどを構造化して記述するための業界標準の仕様である。本章本文では参考資料として挙げられている。本章で手書きするAPI契約のメモと同じく「呼び出し方と返し方を実装前にそろえる」目的を持つが、OpenAPIは機械可読なので、ドキュメント生成やコード生成、テストにも使える。まずは契約を言葉で書けることが土台で、その先に標準フォーマットがある、と捉えるとよい。
具体例：支援ステータス機能のAPI契約を、将来チームで共有・自動検証したくなったら、手書きのAPI契約をOpenAPIの形式で書き直す選択肢がある。
つまずきやすい点：本章ではOpenAPIで書くことは必須ではない。まずは契約の中身（endpoint・request・response・error）を自分の言葉で書けることが先である。
関連語：API（第11章）、HTTP JSON API（第11章）、endpoint（第11章）
テキスト本文での登場箇所：第11章「参考資料」（OpenAPI Specification）

Bearer token

読み：ベアラートークン（Bearer token）
一言で言うと：Authorization headerに載せて認証に使う文字列。
くわしく：Bearer tokenは、Authorization: Bearer <token> の形でrequestに付け、呼び出し元が認証済みであることを示す文字列である。「Bearer（持参人）」の名のとおり、このtokenを持っている人を認証された利用者として扱う。本章のcurl例で認証情報として使われている。tokenは秘密情報なので、AIへ渡したりログやqueryに残したりしないよう注意する。
具体例：支援ステータス更新のcurlで -H "Authorization: Bearer <token>" を付け、ログイン中のメンターとして認証させる。
つまずきやすい点：tokenは秘密情報である。実トークンをコミットしたり、外部サービスやAIに貼ったりしない。
関連語：認証（第11章）、headers（第11章）、401 Unauthorized（第11章）、curl（第11章）
テキスト本文での登場箇所：第11章「curlで、画面がなくてもAPIを確認する」

ISO 8601

読み：アイエスオーはちろくまるいち（ISO 8601）
一言で言うと：日時を文字列で表すときの国際標準フォーマット。
くわしく：2026-05-17T10:00:00+09:00 のように、年月日・時刻・タイムゾーンを決まった順で表す。APIで日時を返すとき、形式がばらばらだと受け手が解釈を誤る。ISO 8601にそろえ、UTC（末尾Z）にするか地域時刻にするかをAPI契約で決めておくと、画面や他システムが安全に扱える。
具体例：支援ステータスの更新時刻を返すとき、2026-05-17T01:00:00.000Z（UTC）で返すか +09:00 付きで返すかを決め、API契約に書く。
つまずきやすい点：タイムゾーンを書かない日時は、どの地域の時刻か分からず誤解のもとになる。オフセットかZを必ず付ける。
関連語：response（第11章）、API（第11章）、headers（第7章）
テキスト本文での登場箇所：第11章「responseは、画面が扱いやすい形で設計する」