Web API: The Good Parts : 感想
書評書籍情報
- Web API: The Good Parts
- 著者名: 水野 貴明
- 出版年: 2014/11/19 (223/ 1/18 11 刷)
- ページ数: 208
読書動機
お仕事でも趣味でも Web API に触れる機会が増え、自分でも実装することが出てきました。
設計指針を学習し、改善しやすい,使いやすい API を作る技術を身に着けることが目的です。
内容要約
本の概要
web api の設計についての本です。
実装面で特定の言語を仮定しないので幅広く読めます。
HTTP の仕様が定まっていない場合はデファクトスタンダードに従う方針です。
利用される API という観点で正しく、また私のような初学者には非常に助かります。
主要なトピック / 章
1 章 Web API とは何か
この書籍で扱うものの定義づけです。
また、設計指針について、美しいWeb API が提示されます。
エンドポイントの設計とリクエストの形式
よい URI と改善点がある URI が例示され説明されます。
可能な限りシンプルかつ分かりやすい URI という基準が明確です。
3 章 レスポンスデータの設計
データフォーマットはほぼ json で決定されています。
しかし、json も深さ、項目などを考慮した設計が必要。
また、エラー発生時に返すデータについても扱います。
エラー情報は HTTP ヘッダに含むことが可能ですが、詳細情報はボディに含みます。
4 章 HTTP の仕様を最大限利用する
HTTP ヘッダに含む情報やステータスコードについて扱います。
レスポンスボディは json を用いますが、本来ヘッダに含めるべき情報をボディに入れて冗長になってしまったり、セキュリティ上の問題の回避について説明されます。
5 章 設計変更しやすい Web API を作る
API のバージョンコントロールについてです。
一度公開した API を停止するのは利用者に迷惑をかけます。
可能な限り迷惑をかけない方法について説明されます。
6 章 堅牢な Web API を作る
API が第三者にハックされたり、悪意のある利用者に不正な情報が送られる、ことを防ぐ方法が説明されます。
付録 A, B
ドキュメント、サンドボックスの提供について、および、Web API のチェックポイント。
理解と学び
理解できたポイント
6 章以外は一通り理解できたと思う。
FastAPI で手を動かしてみます。
学んだこと
- p84 リスト状の情報に続きがあるか？を示す hasNext を返す。 これは聞けばその通りだと思うが自分では思いつかなさそう。
- p93 シンプルとはユーザーが使いやすいということ。
- p96 エラーはレスポンスボディに配列出返す。
- セマンティックバージョニング
- 6 章 ヘッダに残りのリソース(何度アクセス可能か?)を含める。
疑問
理解が不十分な点
- p132 CORS については理解できていない。 一度自分でエラーを出してみないと、理解できなさそう。
- 6 章について、読書中に API 利用者と第三者を混ぜて読んでしまっていた。 途中まで、「その方法では、利用者に不正されるのでは？」と思っていた。
質問や疑問
- json は深くするとサイズが大きくなるらしい。 どの程度大きくなるのだろうか？
次のステップ
興味を持った次の発展
FastAPI で以下のことを調べる・試す
- rateLimit の設定
- ヘッダの設定
応用や実践のアイデア
セマンティックバージョニング 「後方互換なしの変更.後方互換ありの変更.バグ修正」 という方針と「後方互換なしの変更」のみを含める事。
バージンをどこで替えるかあやふやだったのでこれは、すぐに実践する。
読みやすさ評価
文体と構成
なぜ、その方針を取るのか？ ほかに考えられる方針は何か？ が明確に語られており、仕様とデファクトスタンダードも明確で非常に分かりやすと感じました。
文体もわかりやすいものです。
読みやすさ
非常に読みやすい。
しかし、内容は濃い。
私にはとても良い本でした。
感想
1 章に美しいAPI という言葉が出てきます。
まさに求めているものです。 2014 年の本なので少々時代説明は古さがありますが、美しいAPIという言葉には惹かれます。
デファクトスタンダード、推奨方法が明確に語られており、実際に手を動かす指針になる知識が手に入りました。
ただ、内容が多いので記憶は無理です。 しばらく辞書的に使いたいと思います。