「Web API: The Good Parts」を読んだので思ったことを書いていく
なぜ「Web API The Good Parts」を読んだのか
仕事やプライベートではREST APIを作成する機会が多いのですが、そういえばAPIについて体系的に学習したことがなかったなと思い、読むことにしました。
特にレスポンスのデータ設計について自分の中でふわっとした答えしかなく、今までは公開されているAPIを一通り眺めてみて、こんな感じかなと実装していました。
特に読んで気になった箇所を書いていく
全体を読んでみて特に気になった箇所をピックアップして所感など書いていきます。
3.3.3 データはフラットにすべきか
レスポンスのJSONのデータ構造はフラットにすべきかを迷うことが多々あり、いつも直感的にやっていたので、このトピックは大変興味深かったです。
結論から言うとなるべくフラットにすべきだけど階層化したほうが絶対に良い場合は階層化もありというのが、この本の答えのようです。
要するに状況次第ででフラットにすべきかそうでないかを、考慮しろということなのでしょうが、結局の所ここらへんはAPI設計のセンスが問われそうです。
一応、階層的にJSONのデータ構造を設計した場合のデータサイズは、フラット階層にするよりも大きくなってしまうことも多いので、できればフラット階層、でもレスポンスを受け取る側からして見にくいとかの理由を考慮して、階層的にしてもいいよねくらいの、ニュアンスだと受け取りました。
## フラット構造よりも…
{
"title": "title1",
"price": 1000,
"ownerId": 1,
"ownerName": "owner1",
"ownerProfileUrl": "https://example.com"
}
## 階層構造にしたほうがよさそう
{
"title": "title1",
"price": 1000,
"owner": {
"id": 1,
"name": "owner1",
"prorileUrl": "https://example.com"
}
}
## 複数項目をまとめるために階層構造にまとめるのは微妙そう…
{
"id": 111,
"name": "taro yamada",
"profile": {
"birthday": 1203,
"gendar": "male"
}
}
3.3.4 配列とフォーマット
一覧を返却するエンドポイントを作成するときに、配列をそのまま返却するか、オブジェクトで包んで返却するかは迷っていたことでした。
GitHubやFacebookなど既存のAPIを参照して、オブジェクトで包んで返却していたことが多かったため、特に明確な理由がなく僕が作成するときもそうしていたのですが、この本によるとオブジェクトで包んで返却をする実装のほうが良さそうです。
理由は3つあります。
- レスポンスデータが何を示しているものかわかりやすくなる
- レスポンスデータをオブジェクトに統一することができる
- セキュリティ上のリスクを避けることができる
上2つは正直、好みの問題がありそうですが、3つめのセキュリティ上のリスクを避けることができるはかなり重要な理由だと感じています。
トップレベルが配列であるとJSONインジェクションという脆弱性に対するリスクが大きくなります。
参考：「JSON文字列へのインジェクション」と「パラメータの追加」
JSONインジェクションを避けるためにもオブジェクトで包んで返却することを選択したほうがよさそうです。
まとめ
以上、「Web API The Good Parts」を読んで気になった章をピックアップして、自身の感想を書き連ねてみました。
今回とりあげたことはレスポンスのデータ構造に関することが多かったのですが、APIを公開する上でのセキュリティ考慮事項など、なかなか体型的にまとまった情報が少ないトピックも多々あり、良書といえそうです。
Discussion