Kryιk

発展LESSON 16

この教材で学ぶこと resource、status、validation、冪等性を含むAPI契約を設計します。

HTTP API設計

対象読者: 基本文法とHTTPの概要を理解し、Web APIの設計・実装へ進みたい人。

この教材でできるようになること

  • requestとresponseをmethod、path、header、bodyへ分解できる
  • resourceに合うURLとHTTP methodを選べる
  • status codeとerror responseを一貫して設計できる
  • validation、認証、冪等性、paginationを考慮できる

1. APIを契約として捉える

POST /lessons HTTP/1.1
Content-Type: application/json
Idempotency-Key: 0f95...

{"title":"HTTP API設計","level":"advanced"}
HTTP/1.1 201 Created
Location: /lessons/lesson-123
Content-Type: application/json

{"id":"lesson-123","title":"HTTP API設計","level":"advanced"}

clientとserverは、入力、出力、失敗条件を共有する契約で結ばれます。

2. resourceとmethod

操作 method path例
一覧取得 GET /lessons
一件取得 GET /lessons/{id}
作成 POST /lessons
全体置換 PUT /lessons/{id}
部分更新 PATCH /lessons/{id}
削除 DELETE /lessons/{id}

URLには動詞を乱立させずresourceを表し、操作の意味はHTTP methodへ持たせます。ただし既存契約やdomain上のcommandが明確なら、機械的なREST化より一貫性を優先します。

3. status codeを使い分ける

  • 200 OK: 成功しresponse bodyを返す
  • 201 Created: resourceを作成した
  • 204 No Content: 成功したがbodyなし
  • 400 Bad Request: request形式が不正
  • 401 Unauthorized: 認証が必要または失敗
  • 403 Forbidden: 認証済みだが許可されない
  • 404 Not Found: resourceが存在しない
  • 409 Conflict: 現在状態と競合
  • 422 Unprocessable Content: 形式は読めるが値が要件を満たさない
  • 500 Internal Server Error: server側の予期しない失敗

内部例外やstack traceをそのまま外部へ返しません。

4. error responseを統一する

{
  "code": "INVALID_LEVEL",
  "message": "level must be beginner, intermediate, or advanced",
  "details": [
    { "field": "level", "reason": "unsupported value" }
  ],
  "requestId": "req-123"
}

利用者向けmessage、機械判定用code、調査用request IDを分けます。request IDからserver logを追えるようにしつつ、秘密情報をresponseへ含めません。

5. validationと認証認可

検証の順序例:

  1. body sizeやcontent type
  2. JSONとして読めるか
  3. 必須fieldと型
  4. 値の範囲
  5. 認証
  6. 対象resourceへの権限
  7. domain rule

認証済みであることと、そのresourceを操作できることは別です。resource所有者やroleをserver側で検証します。

6. 冪等性とretry

network timeoutでは、serverで成功したのにclientがresponseを受け取れないことがあります。作成や決済のような重複が困る操作では、clientが一意なkeyを送り、serverが同じkeyの結果を再利用する設計を検討します。

GET、PUT、DELETEはHTTP semantics上idempotentですが、実装の副作用まで自動で安全になるわけではありません。

7. pagination

GET /lessons?limit=20&cursor=eyJpZCI6...

大きな一覧を一度に返さず、上限を設けます。並び順を固定し、cursorの改ざんや期限切れを扱います。

演習: 学習教材API

次のendpointについてrequest、成功response、validation error、権限errorを書いてください。

  • 教材を作成
  • 教材一覧をlevelでfilter
  • 教材を完了へ変更
  • 教材を削除

さらに、同じ完了requestが二回来た場合の結果と、同時更新時の競合処理を決めます。

理解チェック

  • requestとresponseの構成要素を説明できる
  • methodとstatus codeを意味から選べる
  • error responseを一貫した形で設計できる
  • retry、冪等性、paginationの必要性を判断できる

公式資料

次に読む

設計とリファクタリングで、APIの内側を変更しやすく保ちます。