APIの受け渡しに使うJSONの書き方

JSONは、"項目名": 値 の組を並べてデータを表す、プログラム同士のやり取りに広く使われるテキスト形式です。通販の荷物に添えられた明細書に「品名: ボールペン」「数量: 3」と書かれていれば、箱を開けなくても中身の見当がつきます。JSONも同じように、項目と中身を組にして書き並べます。

たとえば、ある顧客の情報をJSONで書くと、こうなります。

{
  "name": "田中",
  "age": 42,
  "member": true,
  "orders": [
    { "item": "ボールペン", "quantity": 3 },
    { "item": "ノート", "quantity": 1 }
  ]
}

人が読んでも構造がひと目で分かり、多くのプログラミング言語がそのまま読み書きできます。送る側と受け取る側でプログラムの言語が違っても、この書き方にそろえておけば迷わず読み取れる。だから、APIがデータを返すとき、ブラウザとサーバーが情報をやり取りするとき、アプリの設定を保存するときなど、あちこちで使われています。表の形で並べるのが得意な CSV と比べると、上の orders のように、項目の中にさらに項目を入れた階層も表せるのが特徴です。

1文字違うだけで読めなくなる

書き方が決まっているぶん、決まりから外れると途端に読めなくなります。項目名の綴りが1文字違えば、受け取る側のプログラムはその項目を見つけられません。42 という数値と "42" という文字列を取り違えると、足し算のつもりが文字をつなげてしまうような、想定外の結果になることもあります。

だから、項目名と値の種類（数値か、文字列か、真偽か）は、送る側と受け取る側で最初に合意しておきます。外部から受け取ったJSONは、想定した形になっているかを確かめてから使います。データの量が多くなると目で見て確認するのは難しくなるので、形式のチェックはプログラムに任せるのが確実です。

もう一つ、JSONはただのテキストです。それ自体に暗号化の機能はないので、個人情報や認証情報を載せるなら、HTTPSのように通信経路を守る仕組みを別に用意します。