Web API: The Good Parts 読書メモ
https://www.oreilly.co.jp/books/images/picture_large978-4-87311-686-0.jpeg
Web API: The Good Parts / 水野 貴明 著
積読してた『Web API: The Good Parts』を今さらながら読み始めた。この本はオライリーによくある翻訳本ではなく書き下ろしとなっている。何気なく著者の方を検索してみてヒットしたインタビュー記事が興味深かった。 1章
Web API 設計は美しくあるべき
使いやすさ
変更しやすさ
頑強さ
恥ずかしくない
技術レベルの社外アピール
Web API を美しくするにはどうすればいいか
仕様が決まっているものに関しては仕様に従う
仕様が存在していないものに関してはデファクトスタンダードに従う p15
ProgrammableWeb
The future of API design: The orchestration layer
by Daniel Jacobson (Netflix)
LSUDs (large set of unknown developers)
未知のたくさんの開発者向け
SSKDs (small set of known developers)
既知の少数の開発者向け
SSKDs 向けの API 設計において REST のリソースベースの考え方は不十分
RESTにおけるURIはリソースを表すため、操作を表すような動詞がAPIの中に入ることをよしとしません。しかしたとえば検索の際に「search」という単語を出したほうがわかりやすい場合がありますし、(中略) RESTの精神には反しています。p17
感想
REST に関する本だと思ってたがそれに限定しているわけではなかった
動詞でエンドポイントを定義する場合については我流だったので次章以降に期待が高まった
2.5.4.1 URI に「Search」という単語を入れるべきか p47
2章
人間が理解できる URI にするには
省略形にしない
よく使われる英単語を選択する
たとえば API の文脈においては search がよく使われる
ある場所において探す(search)
あるものを探す(find)
迷ったときは ProgrammableWeb に登録されている API を確認する
パラメータをクエリに入れるかパスに入れるか
一意なリソースを表すのに必要な情報かどうか
ユーザーID の場合、ユーザーIDを指定することで参照したい情報が一意に決まりますからパスに入れたほうがよいでしょう。(中略)しかし一方でたとえばアクセストークンなどをクエリパラメータとして指定するAPI は多くありますが、こちらは利用者の認可が目的であり、リソースとは無関係ですからクエリパラメータのほうが適しています。 p48-49
省略可能かどうか
リストや検索の際のoffset、limit、あるいはpage などのパラメータは省略すればデフォルトの値が利用されるケースが多くなります。したがってクエリパラメータのほうが適しています。p49
設計の美しさよりも実用性を優先する
たとえばユーザのホーム画面を構築するケースを考えた場合、API を複数回呼ぶのではなく、ホーム画面用のAPIをクライアントに提供する。特にSSKDsのようにAPIのユーザが特定のクライアントのみの場合。
感想
REST は設計がきれいになるけど何回も呼び出すのは非効率とは思ってて、この章を読んでSSKDsの文脈ではまとめて返すAPIがあっても問題ないことがわかった
HATEOASはキーワードを昔見かけたくらいで最近はまるで聞かない
アプリの審査対策としては有用そうだが...
3章
共通レスポンスとしてのエンベロープはアンチパターン
HTTPヘッダをエンベロープとして活用する
4章
読了
5章
読了
6章
読了
おわりに
RESTful API のおさらいに最適な書籍
GraphQL が主流になっていくかもしれないが本書の内容は今後も有益