はじめに
Webアプリケーションを開発していると必ず出てくる「API設計」。なんとなくコピペで乗り切っている人も多いのではないでしょうか。
この記事では、初めてAPIを設計する人向けに、最低限おさえておきたい考え方とルールをまとめました。RESTful APIを前提に解説します。
1. APIとは何か
API（Application Programming Interface）とは、プログラム同士がやり取りするための窓口です。
Web APIの多くはHTTPを使って通信し、クライアント（フロントエンドやアプリ）とサーバーの間でデータをやり取りします。
クライアント → リクエスト → サーバー
クライアント ← レスポンス ← サーバー
2. RESTの基本原則
REST（Representational State Transfer）は、Web APIを設計する上で最も広く使われる考え方です。以下の原則を意識しましょう。
- リソース指向：URLは「モノ（リソース)」を表す
- 統一インターフェース：HTTPメソッド（GET/POST/PUT/DELETEなど）で操作を表現
- ステートレス：サーバーはリクエスト間の状態を保持しない
- 階層構造：URLの階層でリソースの関係を表現する
3. リソース設計（URL設計）
3.1 名詞を使う、動詞を使わない
❌ GET /getUser?id=1
✅ GET /users/1
URLは「操作」ではなく「対象（リソース）」を表すべきです。操作はHTTPメソッドで表現します。
3.2 複数形を使う
❌ /user/1
✅ /users/1
コレクションは複数形にするのが一般的な慣習です。
3.3 階層構造で関連を表現する
GET /users/1/posts # ユーザー1の投稿一覧
GET /users/1/posts/10 # ユーザー1の投稿10番
3.4 小文字・ハイフン区切りを使う
❌ /UserOrders
❌ /user_orders
✅ /user-orders
4. HTTPメソッドの使い分け
| メソッド | 用途 | 例 |
|---|---|---|
| GET | リソースの取得 | GET /users/1 |
| POST | リソースの新規作成 | POST /users |
| PUT | リソースの全体更新 | PUT /users/1 |
| PATCH | リソースの部分更新 | PATCH /users/1 |
| DELETE | リソースの削除 | DELETE /users/1 |
ポイント：GETとDELETEは「冪等（べきとう）」、つまり何度実行しても結果が同じになるように設計します。
5. ステータスコードを正しく使う
レスポンスの意味をステータスコードで明示することも重要です。
| コード | 意味 | 使う場面 |
|---|---|---|
| 200 OK | 成功 | 取得・更新成功 |
| 201 Created | 作成成功 | POSTでリソース作成 |
| 204 No Content | 成功（本文なし） | DELETE成功時など |
| 400 Bad Request | リクエスト不正 | パラメータ不足など |
| 401 Unauthorized | 未認証 | ログインしていない |
| 403 Forbidden | 権限なし | 認証済みだが権限不足 |
| 404 Not Found | リソースが存在しない | 該当IDが存在しない |
| 500 Internal Server Error | サーバー内部エラー | 予期しないエラー |
すべて200や500で返すのはNGです。クライアント側がエラー内容を判断できなくなります。
6. レスポンス設計
6.1 一貫したフォーマットにする
{
"data": {
"id": 1,
"name": "山田太郎"
}
}
6.2 エラーレスポンスも統一する
{
"error": {
"code": "USER_NOT_FOUND",
"message": "指定されたユーザーが見つかりません"
}
}
エラーの形式がエンドポイントごとにバラバラだと、フロントエンド側の実装が大変になります。
7. ページネーション（一覧取得の工夫）
大量データを一度に返すとパフォーマンスが悪化します。ページネーションを用意しましょう。
GET /users?page=2&limit=20
レスポンス例：
{
"data": [...],
"pagination": {
"page": 2,
"limit": 20,
"total": 134
}
}
8. バージョニング
APIは後から仕様変更が必要になることがほとんどです。最初からバージョンを切っておくと安全です。
GET /v1/users/1
URLにバージョンを含める方法が最もシンプルでわかりやすいです。
9. 認証・認可
- 認証（Authentication）：「あなたは誰か」を確認する
- 認可（Authorization）：「あなたに何が許可されているか」を確認する
代表的な方式：
- APIキー：シンプルだが管理がやや粗い
- OAuth2.0：第三者サービス連携に強い
- JWT（JSON Web Token）：ステートレスな認証によく使われる
多くの場合、リクエストヘッダーに以下のようにトークンを付与します。
Authorization: Bearer <token>
10. ドキュメント化を忘れない
APIは「使われて初めて価値がある」ものです。仕様書がないと誰にも使ってもらえません。
- OpenAPI（Swagger）：APIの仕様をYAML/JSONで記述し、自動でドキュメント生成できる
- 実際にリクエストを試せるツール（Swagger UIなど）と組み合わせると効果的
11. セキュリティの基本
- HTTPS通信を必須にする
- 入力値のバリデーションを必ず行う（SQLインジェクション対策など）
- レートリミットを設けて過剰リクエストを防ぐ
- 不要な情報をレスポンスに含めない（パスワードハッシュなど）
まとめ
API設計で意識すべきポイントを振り返ります。
- URLは名詞・複数形で「リソース」を表す
- 操作はHTTPメソッドで表現する
- ステータスコードを正しく使い分ける
- レスポンス・エラー形式を統一する
- ページネーション・バージョニングを最初から考慮する
- 認証・認可の仕組みを設計する
- ドキュメントを整備する
- セキュリティを考慮する
参考資料
JISOUのメンバー募集中！
プログラミングコーチングJISOUでは、新たなメンバーを募集しています。日本一のアウトプットコミュニティでキャリアアップしませんか？
興味のある方は、ぜひホームページをのぞいてみてください！