『Web API： The Good Parts』読んだ
『Web API: The Good Parts』を読んだ。贈ってくれた人達ありがとうございます。
目次
詳細はO'Reillyのページにて。
- 1章 Web APIとは何か
- 2章 エンドポイントの設計とリクエストの形式
- 3章 レスポンスデータの設計
- 4章 HTTPの仕様を最大限利用する
- 5章 設計変更をしやすいWeb APIを作る
- 6章 堅牢なWeb APIを作る
所感
Web API、よく知らない場合はとりあえず作りやすい方法で作っていこうという気持ちになりやすい。しかし、Web APIは後から変更するのが比較的難しいものなので、つらいものを使い続ける羽目になりやすい。また一貫性が重要視されやすいので、既に良くないものが存在してしまうと良くない仕様だと分かっていても真似せざるを得ないということが多い。他に、設計を始めるときに初期に想定されているWeb APIクライアントの要求に特化したものを作りがちで、その後クライアントの種類が増えたときに破綻しやすいと思う。
真似するのが良い
大きな方針として既にあるサービスの仕様を積極的に真似していくのは正しいと思っていて、まあ実際狭義のREST APIっぽいものが求められていて且つ特によく分かっていないのであればGitHubのAPIを全面的に参考にしていけばいいと思う。本書では「他の幾つかのサービスはどうしているか」と「著者はどれが良いと思うか」を判断の必要な箇所ごとに説明していってくれている。例えばエンドポイントの命名規則としてアンダースコアとハイフンのどちらを使うべきかという細かいところから、セキュリティの気を付け方としてどういうものがあるかというところまで、広い感じで紹介されている。Web APIの個々の構成要素ごとに、事例と著者の判断が述べてあり、要素要素がカテゴリに分かれていて、それが章立てになっているという様相。要素の分解単位がわかりやすいので読みやすい。「そうだね」と思うところもあれば、「へえ、そう思うんだ」と思うところもある。
実際もっと面倒
よっしゃ感想書くぞ〜と思って意気揚々と編集画面開いてたけど、特にこれ以上気持ちが生まれてこなかった。本書には実装に関わることは(意図的に)書かれていない。実装していくことを考えはじめると、実装のフレームワークどうするか、セキュリティどうするか、具体的には気を付けてるレベルでいいのか監査いくら掛かるのかとか、監視どうするか具体的にはインフラと開発チームとの距離感によってどう変えないといけないのかとか、APIドキュメントと実装の乖離どうするか、APIつくるときサービス開発者主動で開発させた方が良いのかAPIのコアチームっぽい開発者主動で開発させた方がいいのか、そのときのレビュー誰がするか、APIつくってる開発者の評価指標どうするか、他の開発者と情報共有どうするか、公開APIならどう利用者に広めていくか、APIクライアント、非公開API、i18n、あああ色々あるあああ面倒あああああああああああああしかもこういうことは本書には書かれていない。しかし確かに本書で述べられている仕様に関する事柄は必ず考えないといけないことばかりで、説明の粒度も分かりやすい。「APIつくろうとしてるんですけど、どうしたら」という人に説明するときに、とりあえず読んどいてという感じで読ませると良さそう。200ページだしすぐ読めて良いと思う。