REST APIでのJSONの使用：ベストプラクティス

2026-07-19· タグ: json, rest-api, api-design, json-best-practices, pagination, web-development

REST APIにおけるJSON

JSONとREST APIは理想的な組み合わせです。JSONの軽量な構文、ネイティブの配列サポート、そして普遍的な言語サポートにより、JSONは現代のWeb APIのデフォルトフォーマットとなっています。しかし、APIでJSONを使用するだけでは十分ではありません -- 確立された慣習とベストプラクティスに従うことで、APIが一貫性があり、直感的で、統合しやすいものになります。

リクエストとレスポンスの形式

一貫したエンベロープ構造

すべてのAPIレスポンスに一貫したJSONエンベロープを採用してください。これにより、クライアント側の処理が予測可能になり、エラー処理が簡素化されます。

{
  "status": "success",
  "data": {
    "user": {
      "id": 123,
      "name": "Alice",
      "email": "alice@example.com"
    }
  },
  "meta": {
    "requestId": "req-a1b2c3d4",
    "timestamp": "2026-07-19T10:30:00Z"
  }
}

スネークケースとキャメルケース

命名規則を1つ選び、API全体でそれを使い続けてください：

キャメルケース（createdAt、firstName）：JavaScript/TypeScriptエコシステムで一般的
スネークケース（created_at、first_name）：Python、Ruby、PHPエコシステムで一般的

どちらを選んでも明確に文書化し、バックエンド言語が異なる規則を使用している場合は変換レイヤーの使用を検討してください。

JSONとHTTPステータスコード

適切なHTTPステータスコードはJSONレスポンスを補完します。一貫して使用してください：

| ステータスコード | 意味 | 使用場面 | |-------------|---------|-------------| | 200 OK | 成功 | GET、PUT、PATCHの成功 | | 201 Created | リソースが作成された | POSTの成功 | | 204 No Content | 削除の成功 | DELETEの成功（JSONボディなし） | | 400 Bad Request | 無効なJSON構文 | 不正なリクエストボディ | | 401 Unauthorized | 認証が必要 | トークンの欠落または無効 | | 403 Forbidden | 権限が不十分 | 認証は有効だが許可されていない | | 404 Not Found | リソースが存在しない | 無効なIDまたはパス | | 422 Unprocessable Entity | 検証の失敗 | 有効なJSON内の意味的なエラー | | 429 Too Many Requests | レート制限に達した | クライアントが制限を超えている | | 500 Internal Server Error | サーバー側の障害 | 予期しないエラー |

標準的なエラーレスポンス形式

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request body contains invalid fields",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address",
        "code": "INVALID_FORMAT"
      },
      {
        "field": "age",
        "message": "Must be a positive integer",
        "code": "OUT_OF_RANGE"
      }
    ]
  }
}

ネストされたリソース

リレーションシップの表現

REST APIは関連リソースを表現する必要が頻繁にあります。一般的なパターンは次のとおりです：

埋め込み（eager loading）：

{
  "order": {
    "id": 5001,
    "total": 29.99,
    "customer": {
      "id": 123,
      "name": "Alice",
      "email": "alice@example.com"
    },
    "items": [
      {
        "productId": 42,
        "name": "Widget",
        "quantity": 2,
        "price": 14.99
      }
    ]
  }
}

参照（lazy loading）-- IDを使用して個別のエンドポイントを提供：

{
  "order": {
    "id": 5001,
    "total": 29.99,
    "customerId": 123,
    "itemIds": [101, 102]
  }
}

経験則： 常に一緒に必要となる関連データは埋め込みます。条件付きで、または別のタイミングで取得されるデータは参照します。

ページネーションパターン

リソースのリストを返す場合、ページネーションは不可欠です。一貫したページネーション形式を使用してください：

オフセットベースのページネーション

{
  "status": "success",
  "data": [
    { "id": 1, "name": "User 1" },
    { "id": 2, "name": "User 2" }
  ],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "totalItems": 156,
    "totalPages": 8,
    "links": {
      "first": "/api/users?page=1&perPage=20",
      "prev": null,
      "next": "/api/users?page=2&perPage=20",
      "last": "/api/users?page=8&perPage=20"
    }
  }
}

カーソルベースのページネーション（大規模データセットに推奨）

{
  "status": "success",
  "data": [
    { "id": 100, "name": "User 100" },
    { "id": 101, "name": "User 101" }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6MTAxfQ==",
    "hasMore": true
  }
}

カーソルベースのページネーションは、新しいレコードがページ境界を変える可能性のあるリアルタイムデータに対してより信頼性が高くなります。

APIリクエストにおけるJSON

POST / PUTリクエストボディ

Content-Type: application/jsonヘッダーでJSONを受け入れます：

{
  "title": "New Blog Post",
  "content": "This is the content...",
  "tags": ["json", "rest-api"],
  "published": false
}

PATCHによる部分更新

部分更新にはPATCHを使用します。変更する必要のあるフィールドのみを受け入れます：

// PATCH /api/users/123
{
  "email": "newemail@example.com"
}

フィルタリング、ソート、検索

JSONボディをクリーンに保ち、データ操作にはクエリパラメータを使用します：

GET /api/users?filter[role]=admin&sort=-createdAt&search=alice

{
  "status": "success",
  "data": [ /* filtered, sorted results */ ]
}

レート制限

レート制限情報をレスポンスヘッダーに含め、必要に応じてJSONボディにも含めます：

{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again later."
  },
  "meta": {
    "rateLimit": {
      "limit": 100,
      "remaining": 0,
      "resetAt": "2026-07-19T11:00:00Z"
    }
  }
}

JSONベストプラクティスチェックリスト

[ ] 一貫したキー命名を使用する（全体でcamelCaseまたはsnake_case）
[ ] すべてのレスポンスで適切なHTTPステータスコードを返す
[ ] 機械可読なエラーコードを含む一貫したエラー形式を含める
[ ] 標準化されたページネーションオブジェクトでリストエンドポイントをページネーションする
[ ] JSON Schemaを使用してリクエスト/レスポンス構造を文書化し検証する
[ ] すべてのJSONエンドポイントでContent-Type: application/jsonを設定する
[ ] 本番環境ではgzipまたはbrotliでJSONレスポンスを圧縮する
[ ] 最大ペイロードサイズの制限を強制する（例：デフォルト1MB）
[ ] HTTPSを使用して転送中のJSONデータを暗号化する
[ ] 内部を公開せずにクライアントがデバッグできるようにエラー詳細を構造化する

API JSONの検証

クライアントに到達する前にフォーマットエラーを検出するため、APIレスポンスをJSONバリデーターに通してください。一貫性のある有効なJSONレスポンスは、APIを信頼性が高く開発者に優しいものにします。開発中は当サイトのJSONフォーマッター＆バリデーターツールを使用してペイロードをテストしてください。