「Web API The Good Parts」をしっかり読んだ
2014 年、結構前の本だったのか。
書籍自体は買っていたけれど、リファレンス的というか、流し読みすらしてなくてかじり読みみたいな感じになっていたので、しっかり読んでみた。
Scrapbox にメモ取りながら読んで行ってたんだけど、メモなのに結構なボリュームになってしまったので公開できない感じに 😩
記憶に残った点
全体的に
この書籍の大事にしている部分でもあるが、正解が無いような部分でも、他の大手の Web サービスの事例を分析し、（その時点の）ベストプラクティスを実践していこうというのがいい感じだなと思った。
Web API だけでなく、たまに原理主義的になってしまうケースを見かけるが、それでは上手く行かない場合や、チームとして付いていけないメンバーを作ってしまうケースもあるので、現実の多くのプロダクトを参考にするというのは現実的だなと思う。
単語をつなげる必要がある場合はハイフンを利用する
SEO的な観点と URI にはアンダースコアは使えないの２つの観点があるという事を知らなかった。なんとなく後者だけの理由で「ハイフン使う」みたいに思っていたけど、他にも観点があるのを知れてよかった。
q=word は全文検索のイメージ
あんまり意識したことなかったけど、たしかにそう思っていることがあるなと。
ログインと OAuth 2.0
OAuth を使うことはあっても、割と SDK でぱっと済ませてしまうことがあって、体系的なことが改めて整理されてよかった。
すごく昔に以下の本を読んで分かった気になっていたのを思い出した。
O'Reilly Japan - OAuth 2.0をはじめよう
HATEOAS と REST LEVEL 3 API
何年か前の Ruby Kaigi で Faraday とその拡張を使って HATEOAS の URL をどんどん辿っていけるデモを見た記憶がある。
今だと、これはどういう扱いなんだろ。
データフォーマットの指定方法
クエリパラメータ、拡張子、ヘッダと 3 種類が例に上がっているが、個人的な意外な感じでクエリパラメータが推薦されている。ヘッダ使えとかになるのかと思ったけど、こういう選択をしてくるのはいいな。
配列とフォーマット
JSON インジェクション、なんかハマった記憶が。
性別のデータ
gender の種類の多さ、sex との意図の違いは、全然知らなかったので新鮮。
HTTP ヘッダには RFC 3339 は使えない
知らなかった 😅
エラーの詳細をクライアントに返す
こういうのを知りたくて、リファレンスっぽく使ってたけど、改めて読むと忘れてることが多い。
メンテナンスとステータスコード
Retry-After 使ってなかったな 😩
202 Accepted
処理が完了するまでの時間を Retry-After に入れる事例があるの面白いなぁ。
204 No Content
DELETE が空のレスポンスはいいとして、PUT/PATCH は ETag 用の情報を得る意味でもコンテンツを返すというのはなるほど。
406 Not Acceptable
普通に使ったこと無いし、意識したことない。
500 番台 サーバーに問題があった場合
500と503の違い、ちゃんと意識してなかったなぁ。。
Heuristic Expiration (発見的期限切れ)
クライアントがなんとなく更新頻度とかを判断するというのは考えたことなかった。
Vary でキャッシュの単位を指定する
意識して使ったことが無かったけど、たしかに見たことはあった。
Cache-Control ヘッダ
ほんとに「へーーー」という感じ。
x-で始まるメディアタイプ / 自分でメディアタイプを定義する場合
この歴史的な部分とか、vnd 以外にもあるとか知らなかった。
CORS プリフライトリクエスト
聞いたことはあったけど、実際どういうものかよく分かってなかった部分。
CORS とユーザー認証情報
ちゃんと理解できてなかった部分。
API バージョン、どの方法を採用するべきか
URI のパスに含めるのが一般的ということらしい。Github 見てると確かにヘッダに入ってるなと思っていたけど、Google も部分的にしか利用していないらしい。
今はどうなんだろうな。
セキュリティ関係の HTTP ヘッダ
Rails 使ってると以下のような Gem で一気に追加したりするけど、個別に見ていくとよく理解できる。
GitHub - twitter/secure_headers: Manages application of security headers with many safe defaults
レートリミットの単位
Etsy のやり方は面白い。
レートリミットをユーザに伝える
内部向けの API ばかり書いていたので、こういうユーザに伝える方法はあまり意識してなかった。
最後に
もう日本語版の出版から 5 年経っているので、今だと変わっている部分も多いんだろうなぁと。
GraphQL や gRPC といった、REST が担っていた箇所を（部分的 | 全体的) に置き換える技術もこの 5 年で使われてきているので、その辺りとも比べながらキャッチアップしていきたいなと思う。
