🚀

API設計で考えること

に公開
api設計
tech

API設計で考えること

API設計は「リクエストを受けてレスポンスを返す」だけではありません。
利用する人（フロントエンド、外部開発者、将来の自分）が使いやすく、拡張しやすい形を考えることが重要です。ここでは設計時に意識しておきたい観点を整理します。

インターフェース

APIの入り口であるエンドポイントは、利用者にとって直感的でなければなりません。

  • リソースは名詞で表現し、操作はHTTPメソッドに委ねます。

    • 例: GET /users/123（ユーザー取得）、POST /users（ユーザー作成）

  • 余計な動詞は付けず、URL構造だけで対象がわかるようにします。

  • バージョン管理も大切です。古いクライアントを壊さないために、/v1/users のように明示します。

これを守ることで「どんなAPIが用意されているか」が直感的に理解できるようになります。

バリデーション

クライアントからの入力は常に不正の可能性があります。

  • 必須チェック、型チェック、文字数制限などをサーバー側で必ず行います。
  • エラー時は 422 Unprocessable Entity を返すのが一般的です。

さらに「どのフィールドが何でNGなのか」を返すことが大切です。

{
  "errors": [
    { "field": "email", "message": "Invalid email format" }
  ]
}

こうしておくと、クライアントは即座にフィードバックできます。

エラー設計

エラーを返すときは統一した形式を徹底します。
バラバラに返すとクライアント側で処理が複雑になってしまうためです。

例えば RFC7807 に準拠した application/problem+json 形式がおすすめです。

{
  "type": "https://example.com/probs/auth/invalid-credentials",
  "title": "Invalid credentials",
  "status": 401,
  "detail": "Email or password is incorrect"
}

どんなエラーが起きたのか、どう扱えばよいのかが明確になります。

認証

「誰がアクセスしているか」を確認する仕組みも重要です。

  • 公開APIなら Bearerトークン（JWTやOAuth 2.0） が標準。
  • 同一ドメインのSPAなら Cookie + CSRF 対策で十分な場合もあります。
  • エンドポイントごとにロールやスコープを割り当て、細かいアクセス制御を実装します。

これにより、権限のないユーザーが勝手に操作することを防げます。

ステータスコード

HTTPステータスはAPIの言葉そのものです。
適切に使うことで、レスポンス本文を読まなくても状況がわかります。

よく使うものを整理すると：

  • 200 OK（成功）
  • 201 Created（新規作成成功）
  • 204 No Content（処理成功だが返すものなし）
  • 400 Bad Request（リクエストが壊れている）
  • 401 Unauthorized（認証が必要）
  • 403 Forbidden（権限不足）
  • 404 Not Found（存在しない）
  • 409 Conflict（二重登録など競合）
  • 422 Unprocessable Entity（バリデーションエラー）
  • 500 Internal Server Error（サーバー側のバグ）

これを正しく返せるだけで、APIの使いやすさは格段に向上します。

その他の観点

より本格的に設計するなら以下も考慮します。

  • ページネーション・ソート・フィルタ … 一覧取得に必須
  • Rate Limit（429 Too Many Requests） … 濫用防止や負荷対策
  • 冪等性（Idempotency-Key） … 決済などでの二重実行防止
  • セキュリティ … HTTPS必須、CORS制御、入力サニタイズ
  • ロギング・監査 … 誰がいつ何をしたかを追跡可能にする
  • 日付・時刻 … ISO 8601形式でUTCを基本に
  • キャッシュ戦略 … ETag や Cache-Control ヘッダを活用

これらは後から追加すると破壊的変更になりやすいため、最初から意識しておくのが望ましいです。

設計書（ドキュメント）

最後に欠かせないのがドキュメント化です。

  • OpenAPI (Swagger) 形式で残すのがベストプラクティスです。
  • エンドポイント、リクエスト/レスポンス、ステータスコード、認証方式を明記しておくと、フロントエンドや外部開発者が安心して利用できます。

これだけ押さえておけば、API設計は「とりあえず動く」から「誰が使っても迷わない」レベルに引き上げられます。

付録：API設計チェックリスト

APIを設計するときに見落としがちなポイントを確認するためのチェックリストです。記事本文の内容を簡潔にまとめています。

  • リソースを名詞で設計したか？（例: /users, /projects/123）
  • バージョン管理の方法を決めたか？（URL /v1 か Acceptヘッダ）
  • 入力値のバリデーションを定義したか？（必須・型・桁数・正規表現など）
  • エラーレスポンスの形式を統一したか？（例: application/problem+json）
  • 認証方式を決めたか？（JWT / OAuth 2.0 / Cookie+CSRF）
  • 権限（role/scope）の制御ルールを決めたか？
  • 適切なHTTPステータスコードを返すよう整理したか？
  • ページネーション・ソート・フィルタの仕様を決めたか？
  • レート制限（429 Too Many Requests）の設計をしたか？
  • 冪等性が必要な操作を洗い出し、Idempotency-Key を導入したか？
  • HTTPS必須か？CORS制御を設定したか？
  • ログ／監査ログの出力ルールを決めたか？
  • 日付・時刻はISO8601でUTCを基本にしたか？
  • キャッシュ制御（ETag / Cache-Control）を設計したか？
  • OpenAPI (Swagger) で仕様を残したか？

Discussion