JSONキーの命名規則：APIにおけるcamelCase vs snake_case
5 分で読了
JSON仕様にはキーの命名規則に関する規定がありません。仕様上、キーは「文字列」とだけ定義されており、ケースの指定はありません。実務ではcamelCaseとsnake_caseの2つが主流となっています。
主要APIの採用状況
| API / プラットフォーム | 規則 | 例 |
|---|---|---|
| Google APIs | camelCase | {"userId": 1, "displayName": "Alice"} |
| Twitter/X API | snake_case | {"user_id": 1, "screen_name": "alice"} |
| GitHub API | snake_case | {"login": "alice", "avatar_url": "..."} |
| Stripe API | snake_case | {"customer_id": "cus_123", "created_at": 1234} |
| Firebase | camelCase | {"createdAt": "...", "userId": "abc"} |
| AWS APIs | PascalCase | {"InstanceId": "i-123", "State": "running"} |
camelCaseを推す理由
- JavaScriptのネイティブスタイルであり、フロントエンドで変換不要
- GoogleのJSON Style Guideで推奨されている
- アンダースコアがない分、snake_caseより短い
- Web/モバイルクライアントが主な消費者のAPIに自然にフィットする
snake_caseを推す理由
- アンダースコアが単語境界を視覚的に示し、可読性が高い
- Python、Ruby、SQLのネイティブスタイルであり、バックエンドで変換不要
- 最大級のAPI（GitHub、Twitter、Stripe）の大半が採用している
- データベースのカラム名（ほぼ常にsnake_case）と一貫性が保てる
本当の答え：スタックに合わせる
最適な規則は、JSONの生成側と消費側によって決まります。
| シナリオ | 推奨 | 理由 |
|---|---|---|
| JSバックエンド + JSフロントエンド | camelCase | どこでも変換不要 |
| Python/Rubyバックエンド + 任意のフロントエンド | snake_case | バックエンドの慣例に合致、フロントエンド側で変換可能 |
| 多言語対応の公開API | snake_case | より広い開発者に読みやすい |
| 内部マイクロサービス | どちらでも（統一が重要） | 内部の一貫性が最優先 |
境界での変換
実際の開発では、多くのチームがAPIの境界でJSONキーを変換しています。Pythonバックエンドがsnake_caseで返し、ミドルウェアやクライアント側のユーティリティがReactフロントエンド用にcamelCaseへ変換する、というパターンです。humps（JavaScript）やdjangorestframework-camel-case（Python）などのライブラリがこれを自動化します。
良いJSONキーのルール
- 一貫性を保つ。同じレスポンス内で
userIdとuser_nameを混在させない。 - 説明的な名前を使う。
createdAtであってcaではない。 - 略語を避ける。
organizationIdであってorgIdではない。 - 配列には複数形を使う。リストには
itemsであってitemではない。 - 3階層以上のネストを避ける。可能な限りフラットにする。
JSONキーを即座に変換
JSONキーをcamelCaseに変換またはJSONキーをsnake_caseに変換できます。プレーンテキストの変換にはcamelCaseコンバーターやケースコンバーターハブをご利用ください。