API設計の基本 — RESTfulなエンドポイントの設計ルール

フロントエンドとバックエンドをつなぐAPIは、チーム開発において最も重要なインターフェースです。 API設計が雑だと、フロントエンド側が個別対応に追われ、バックエンド側も一貫性のないコードになります。

この章では、RESTfulなAPI設計のルールと、実務で迷いやすいポイントを整理します。

学習者

APIのURLって自由に決めていいの？チームで作るとバラバラになりがち…ルールってあるの？

RESTの基本原則

REST（Representational State Transfer）は「リソース」を中心に考える設計スタイルです。

⭕ /api/users/123        — ユーザーというリソース
❌ /api/getUser?id=123   — 動詞が入っている
❌ /api/deleteUser/123   — 操作がURLに含まれている

HTTPメソッドの使い分け

以下のセクションは現在執筆中です。

• レスポンス形式の統一（エンベロープパターン）
• ページネーション設計（cursor vs offset）
• バージョニング戦略（URL vs ヘッダー）

ステータスコードの選び方

APIを利用する開発者がエラーハンドリングを正しく実装するには、ステータスコードが一貫したルールで返されている必要があります。

エラーレスポンスの形式もプロジェクト全体で統一しておくと、フロントエンド側が共通のエラーハンドリングを組めます。

{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "指定されたIDのユーザーが存在しません",
    "details": []
  }
}

APIリファレンスの書き方

APIリファレンスは「開発者がAPIを使うときに最初に見るドキュメント」です。 書き方が悪いと、利用者はソースコードを読むか、試行錯誤するしかなくなります。

リソースとは

REST APIにおけるリソースとは、APIが扱うデータの単位です。 たとえばECサイトなら「ユーザー」「商品」「注文」「カート」がリソースにあたります。

各リソースには対応するエンドポイント（URL）があり、HTTPメソッドで操作を表現します。

リソース: ユーザー（users）
├── GET    /api/users          → ユーザー一覧を取得
├── POST   /api/users          → ユーザーを新規作成
├── GET    /api/users/:id      → 特定のユーザーを取得
├── PATCH  /api/users/:id      → ユーザー情報を更新
└── DELETE /api/users/:id      → ユーザーを削除

APIリファレンスに含めるべき項目

網羅的なAPIリファレンスには、以下の情報がすべてのエンドポイントに対して記載されています。

実際のリファレンス例

以下は1つのエンドポイントに対する記述例です。このレベルで書かれていれば、利用者はソースコードを読まずにAPIを使えます。

## ユーザー取得

指定されたIDのユーザー情報を返します。

### エンドポイント

GET /api/users/:id

### パラメータ

| パラメータ | 位置 | 型 | 必須 | 説明 |
|---|---|---|---|---|
| id | パス | integer | はい | ユーザーID |

### リクエスト例

  GET /api/users/42
  Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

### レスポンス例（200 OK）

  {
    "id": 42,
    "name": "田中太郎",
    "email": "tanaka@example.com",
    "role": "editor",
    "created_at": "2025-03-01T09:00:00Z"
  }

### エラーレスポンス

| ステータス | エラーコード | 説明 |
|---|---|---|
| 401 | UNAUTHORIZED | 認証トークンが無効または未指定 |
| 403 | FORBIDDEN | このユーザー情報へのアクセス権がない |
| 404 | USER_NOT_FOUND | 指定されたIDのユーザーが存在しない |

学習者

APIリファレンスって全部手で書くの？エンドポイントが増えるたびにメンテするの大変そう…

先生

実務ではOpenAPI（Swagger）でスキーマを定義して、リファレンスを自動生成するのが主流だよ。でも自動生成する場合でも「何を書くべきか」を知っていないと、中身のないリファレンスが量産されるだけだからね。

ちゃんと使うためのポイント

• URLはリソース（名詞）で構成し、操作はHTTPメソッドで表現する
• レスポンス形式はプロジェクト全体で統一する
• ステータスコードを正しく使い分けることで、フロントエンド側の分岐がシンプルになる
• APIリファレンスにはエンドポイント・パラメータ・リクエスト例・レスポンス例・ステータスコード・エラーメッセージを網羅する
• 迷ったらHTTP仕様に立ち返る

次の章では、API設計の前提となるURL設計とルーティングを掘り下げます。