「APIって聞いたことあるけど、設計となると何から始めればいいの？」

Webサービスやアプリ開発では、API（Application Programming Interface）の理解が欠かせません。特にバックエンドエンジニアを目指すなら、API設計の基本は必須スキルです。

この記事では、最もよく使われるREST APIを中心に、API設計の基本と実践的なポイントを解説します。

APIとは？

APIとは、ソフトウェア同士がやり取りするための窓口のことです。

レストランで例えると、APIは「メニュー」のようなものです。お客さん（フロントエンド）はメニューを見て注文し、厨房（バックエンド）が料理を作って提供します。メニューがなければ、何が注文できるかわかりませんよね。

Web APIでは、フロントエンドがHTTPリクエストを送り、バックエンドがJSONなどの形式でデータを返すのが一般的です。

REST APIの基本原則

REST（Representational State Transfer）は、APIを設計するための設計思想（アーキテクチャスタイル）です。RESTに従って設計されたAPIを「RESTful API」と呼びます。

RESTの6つの原則

特に重要なのはステートレスです。サーバーはリクエスト間で状態を保持しないため、各リクエストには必要な情報をすべて含める必要があります。

HTTPメソッドの使い分け

REST APIでは、HTTPメソッドで操作の種類を表現します。

これを「CRUD操作」（Create, Read, Update, Delete）と呼びます。

エンドポイントの設計

エンドポイントとは、APIにアクセスするためのURLのことです。良いエンドポイント設計は、APIを使いやすくします。

基本ルール

エンドポイントは名詞で、複数形を使うのが一般的です。

# 良い例
GET /users          # ユーザー一覧を取得
GET /users/123      # ID:123のユーザーを取得
POST /users         # 新しいユーザーを作成
PUT /users/123      # ID:123のユーザーを更新
DELETE /users/123   # ID:123のユーザーを削除

# 悪い例
GET /getUser        # 動詞を使っている
GET /user           # 単数形
POST /createUser    # 動詞が重複

階層構造の表現

リソースの関係性は、URLの階層で表現します。

# ユーザーの投稿一覧
GET /users/123/posts

# ユーザーの特定の投稿
GET /users/123/posts/456

# 投稿へのコメント一覧
GET /users/123/posts/456/comments

検索やフィルタリング

検索条件はクエリパラメータで指定します。

# ページネーション
GET /users?page=2&limit=20

# 検索
GET /users?name=田中

# ソート
GET /users?sort=created_at&order=desc

# 複合条件
GET /users?status=active&role=admin

HTTPステータスコード

レスポンスには適切なステータスコードを返すことが重要です。

よくある間違いは、「削除成功」なのに200を返したり、「認証エラー」なのに400を返したりすることです。適切なコードを返すことで、クライアント側でのエラーハンドリングが容易になります。

レスポンス形式

現在のWeb APIでは、JSON形式が標準です。

成功レスポンスの例

{
  "data": {
    "id": 123,
    "name": "田中太郎",
    "email": "tanaka@example.com",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

一覧レスポンスの例

{
  "data": [
    { "id": 1, "name": "田中太郎" },
    { "id": 2, "name": "佐藤花子" }
  ],
  "meta": {
    "total": 100,
    "page": 1,
    "per_page": 20
  }
}

エラーレスポンスの例

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "入力内容に誤りがあります",
    "details": [
      { "field": "email", "message": "メールアドレスの形式が正しくありません" }
    ]
  }
}

API設計のベストプラクティス

1. バージョニング

APIは将来変更される可能性があるため、バージョンを含めます。

# URLにバージョンを含める（推奨）
GET /v1/users
GET /v2/users

# ヘッダーで指定する方法もある
Accept: application/vnd.example.v1+json

2. 一貫性を保つ

命名規則、レスポンス形式、エラー形式など、API全体で一貫性を保つことが重要です。snake_caseとcamelCaseを混在させない、エラー形式を統一するなど、ルールを決めて守りましょう。

3. ドキュメントを整備する

APIはドキュメントがなければ使えません。OpenAPI（Swagger）などのツールを使って、自動生成することをおすすめします。

まとめ

この記事で解説した内容をまとめます。

良いAPI設計は、使う人のことを考えた設計です。自分がAPIを使う立場になって、わかりやすいか、使いやすいかを常に意識しましょう。