導入
たきの「博士〜！」
たきの「REST APIは分かってきたんですが、今度はJSON APIって言葉を見つけました！」
博士「ふむ。」
博士「名前は似ておるが、役割は少し違うんじゃ。」
たきの「また新しいAPIですか？」
博士「では、今日はJSON APIについて学んでいこう。」
JSON APIって何ですか？
博士「JSON APIとは、JSON形式でデータをやり取りするときの書き方を統一するルールじゃ。」
たきの「REST APIとは違うんですか？」
博士「REST APIはAPI全体の設計方法じゃ。」
博士「一方JSON APIは、レスポンスやリクエストのJSONをどんな形で書くかを決めた仕様なんじゃ。」
たきの「役割が違う！」
JSONとは？
たきの「そもそもJSONって何でしたっけ？」
博士「JSONとは、データを表現するための形式じゃ。」
例えばユーザー情報なら、
{
"name": "たきの",
"age": 20
}
のように書く。
博士「REST APIでも、このJSON形式でデータをやり取りすることが多い。」
なぜJSON APIがあるの？
たきの「JSONで送れるなら、それで十分じゃないんですか？」
博士「実はAPIごとにJSONの書き方が違うことがある。」
例えば、
API①
{
"name": "たきの"
}
API②
{
"userName": "たきの"
}
API③
{
"user": {
"name": "たきの"
}
}
たきの「全部違いますね…。」
博士「APIごとに書き方が違うと、利用する人は毎回覚え直さなければならない。」
博士「そこで生まれたのがJSON APIじゃ。」
博士「JSON APIでは、データの形が決められている。」
例えば、
{
"data": {
"type": "users",
"id": "1",
"attributes": {
"name": "たきの"
}
}
}
博士「会社ごとに履歴書の書き方が全部違ったらどうじゃ？」
たきの「応募するたびに新しい書き方を覚えないといけませんね…。」
博士「だから履歴書にはある程度決まった様式がある。」
博士「JSON APIも、誰が見ても同じように読める書き方を決めているんじゃ。」
JSON APIのメリット
たきの「書き方を統一できる以外にもメリットはあるんですか？」
博士「もちろんじゃ。」
博士「例えばこんなメリットがある。」
| メリット | 説明 |
|---|---|
| APIごとの差が少ない | APIごとにJSONの書き方を覚え直さなくて済む |
| チーム開発しやすい | 全員が同じルールで開発できる |
| 保守しやすい | コードの読み方が統一される |
| 関連データを扱いやすい | relationshipsでデータ同士のつながりを表現できる |
たきの「みんな同じルールなら、新しく開発に参加した人も分かりやすそうですね！」
博士「そういうことじゃ。」
よく出てくる項目
博士「JSON APIでは、この4つをよく使う。」
| 項目 | 役割 |
|---|---|
| data | データ本体 |
| type | データの種類 |
| id | データのID |
| attributes | 実際のデータ |
例えば、
{
"data": {
"type": "users",
"id": "1",
"attributes": {
"name": "たきの"
}
}
}
博士「この場合、
- type は users
- id は 1
- attributes に名前などの情報
という意味じゃ。」
relationshipsとは？
たきの「博士！」
たきの「ユーザー情報だけなら分かったんですが…」
たきの「ユーザーが投稿した記事や、購入した商品みたいに、他のデータとつながっている場合はどうするんですか？」
博士「良い質問じゃ。」
博士「JSON APIでは、そのような関連するデータを表すためにrelationshipsという項目を使うんじゃ。」
例えば、
{
"data": {
"type": "users",
"id": "1",
"relationships": {
"posts": {
"data": [
{
"type": "posts",
"id": "10"
}
]
}
}
}
}
博士「これは、『ユーザーID1は投稿ID10と関連しています』という意味じゃ。」
たきの「なるほど！」
たきの「ユーザーと投稿をつなげる役割なんですね！」
博士「その通りじゃ。」
REST APIとの違い
たきの「REST APIとの違いが少し混乱してきました…。」
博士「表で見てみよう。」
| REST API | JSON API |
|---|---|
| API全体の設計方法 | JSONデータの書き方を決める仕様 |
| URLやHTTPメソッドを決める | JSONの構造を決める |
| GET・POSTなどを使う | dataやattributesなどを使う |
博士「つまり、役割が違うんじゃ。」
たきの「REST APIが設計図で、JSON APIはデータの書き方なんですね！」
博士「その理解でよいぞ。」
JSON APIを使う流れ
博士「ユーザー一覧を取得する例で見てみよう。」
① クライアントがリクエスト
GET /users
↓
② APIがデータベースを検索
↓
③ JSON API形式へ変換
{
"data": [
{
"type": "users",
"id": "1",
"attributes": {
"name": "たきの"
}
}
]
}
↓
④ クライアントが受け取る
↓
⑤ attributesの内容を画面へ表示する
たきの「REST APIの流れはそのままで、返ってくるJSONの形だけが統一されるんですね！」
博士「その通りじゃ。」
JSON APIは必ず使うんですか？
たきの「REST APIなら必ずJSON APIを使うんですか？」
博士「いや、必ずではない。」
博士「多くのREST APIは独自のJSON形式を使っている。」
博士「JSON APIは『このルールでJSONを書きましょう』という選択肢の一つなんじゃ。」
たきの「だから普通のREST APIでもJSON APIじゃないものが多いんですね！」
博士「その通りじゃ。」
まとめ
JSON APIとは、
- JSONデータの書き方を統一する仕様
- REST APIとは役割が違う
-
data・type・id・attributesなど決まった構造を持つ - 大規模開発やチーム開発でよく利用される
博士「REST APIはAPI全体の設計方法、JSON APIはJSONの書き方なんじゃ。」
たきの「REST APIとの違いも分かりました！」
博士「ふむ。」
博士「では、今日の一句」
今日の一句
JSON 形そろえて 迷わない