JSON API のベストプラクティス

一貫した JSON 設計は API の消費と保守を容易にします。以下の規約に従うと連携がスムーズになります。

命名と構造

camelCase または snake_case を一貫して使用。ネストは 2〜3 レベルまで。配列はリスト、オブジェクトはエンティティに使い分けます。

null とエラー

null とフィールド欠落を明確に区別。エラーは {"error": {"code": "...", "message": "..."}} 形式で構造化してください。

検証

デプロイ前に JSON を検証。CI で JSON Schema を使うと効果的です。