📛

APIの返り値として返すJSONのベストな形式

に公開
API
JSON
tech

APIの返り値として返すJSONのベストな形式には、いくつかの共通したベストプラクティスがあります。

ベストなJSONレスポンス設計のポイント

  • 一貫性のある構造

    • すべてのAPIで同じ構造（例：status, data, meta, error など）を持たせることで、利用者が扱いやすくなります。

  • プロパティ名はキャメルケース

    • JavaScriptの命名規則に合わせて、プロパティ名はキャメルケース（例：userName）で統一するのが推奨されています。

  • ネストは必要最低限に

    • JSONのネストは深くしすぎず、フラットな構造を心がけることで可読性と扱いやすさが向上します。

  • 値がない場合も明示する

    • データが存在しない場合でも、キーを省略せずに null や空配列などで「値がない」ことを明示するのが望ましいです。

  • メタ情報やページネーション情報の付加

    • リスト系レスポンスには meta や pagination などの情報を含めると、クライアント側での扱いが便利になります。

  • エラー時の標準化

    • エラー時は status, message, errors, code などを含め、エラー構造を統一します。

推奨されるJSONレスポンス例

正常系

{
  "status": "success",
  "data": {
    "id": 123,
    "userName": "taro",
    "email": "taro@example.com"
  },
  "meta": {
    "pagination": {
      "page": 1,
      "perPage": 10,
      "total": 100
    }
  }
}

エラー系

{
  "status": "error",
  "message": "Validation failed",
  "errors": {
    "email": ["メールアドレスの形式が不正です"]
  },
  "code": 422
}

まとめ

  • 一貫性のある構造、キャメルケース、適切なネスト、値がない場合の明示、メタ情報の付加、エラー構造の標準化がベストプラクティスです。
  • これらを守ることで、APIの利用者にとって扱いやすく、保守性の高いAPI設計が実現できます。

Discussion