RESTful API 設計で失敗しないための7つの原則

はじめに

API の設計は、一度公開すると変更が難しいです。本記事では、長期運用に耐える RESTful API を設計するための7つの原則を、実際のコード例とともに紹介します。

1. リソース指向の URL 設計

URL はリソースを表す名詞で構成します。動詞は HTTP メソッドで表現します。

# Good
GET    /api/v1/users
POST   /api/v1/users
GET    /api/v1/users/:id
PATCH  /api/v1/users/:id
DELETE /api/v1/users/:id

# Bad
GET    /api/v1/getUsers
POST   /api/v1/createUser
POST   /api/v1/deleteUser/:id

2. 適切な HTTP ステータスコード

レスポンスには適切なステータスコードを返します。

3. 一貫したエラーレスポンス

エラーレスポンスのフォーマットを統一します。

{
  "statusCode": 422,
  "message": "Validation failed",
  "errors": [
    {
      "field": "email",
      "message": "メールアドレスの形式が正しくありません"
    }
  ]
}

4. ページネーション

リスト系エンドポイントには必ずページネーションを実装します。

GET /api/v1/users?page=1&limit=20

{
  "data": [...],
  "meta": {
    "page": 1,
    "limit": 20,
    "totalItems": 150,
    "totalPages": 8
  }
}

5. フィルタリングとソート

クエリパラメータでフィルタリングとソートをサポートします。

GET /api/v1/orders?status=pending&sort=-createdAt
GET /api/v1/users?role=admin&search=tanaka

6. バージョニング

URL にバージョンを含める方式がシンプルで分かりやすいです。

/api/v1/users
/api/v2/users

7. レート制限

API の安定性を保つために、レート制限を設けます。

// NestJS での実装例
@Controller("api/v1")
@UseGuards(ThrottlerGuard)
@Throttle({ default: { limit: 100, ttl: 60000 } })
export class ApiController {}

まとめ

API 設計は「後から直せばいい」では済みません。最初の設計段階でこれらの原則を押さえておくことで、長期運用でも破綻しない API を構築できます。