RESTful API JSON Response Design: 良い設計の実例
2024-06-28
エンドポイントごとに応答形がバラバラだと、クライアントは毎回アダプターが必要になります。最小限の共通規約が開発速度を守ります。
Envelope
{ data, meta, errors } を使うかどうかより、全 API で一貫していることが重要です。
{ "data": { "id": 1 }, "meta": { "requestId": "abc" } }Error 形
HTTP ステータスに加えて機械判定コード・人向け文言・フィールド詳細を返します。
ページング
Cursor か Offset のどちらかをサービス全体で統一し、配列キー名も固定します。
命名と時刻
camelCase か snake_case を混在させず、日時は ISO 8601 文字列を採用します。
進化戦略
v1 は追加的変更を基本にし、破壊的変更は v2 へ分離して互換性を守ります。