はじめに

「Web API: The Good Parts」を読んでみたので感想や気づきをまとめました。

対象者

この記事は下記のような人を対象にしています。

駆け出しエンジニア
プログラミング初学者
初めてAPI設計する人

結論

「とりあえずAPIって何？」という状態から抜け出せる1冊。
ベテランエンジニアは大体読んだことあるので、彼/彼女らの使ってる単語の意味がわかるようになるだけでも前進だと思います！
ただし、この一冊だけで「API完全に理解した」とはならないので要注意。
あくまで最初の一歩を踏み出したい人向けです。

1章　Web APIとは何か

「まぁそうだよね」という内容が多い。
そもそも2014年初版の本なので、2025年に読むと「今更Facebookの話？」って感じではある。

2章　エンドポイントの設計とリクエストの形式

URIに使う単語はできるだけ1単語にすべき。
get_user_nameのようになっているのはよくない
クエリパラメータvsパス
- 一意なリソースを表すのに必要→パス
- 省略可能→クエリパラメータ

3章　レスポンスデータの設計

リクエスト同様、使う単語は1単語にしたい(当たり前か)

4章　HTTPの仕様を最大限利用する

生成元とはスキーム(httpsなど)・ホスト(example.comなど)・ポート番号の組み合わせで決まる
- つまり、http://example.com と http://example.com:8000 は異なる生成元なので、CORSが必要

5章　設計変更をしやすいWeb APIを作る

バージョン管理
- URI / パスパラメータ / メディアタイプに入れることができる
- 特にどれが良い、はないがURI形式がメジャー

6章　堅牢なWeb.APIを作る

XSS
- 対策：JSON文字列のエスケープ
XSRF
- 対策：XSRFトークンの利用
JSONハイジャック
- 対策：JSONのトップレベルを配列ではなくオブジェクトにする

WEB APIチェックリスト

巻末の付録Bのチェックリストがこの本のまとめとなっているので、引用します。
ちょっと多すぎて覚えきれないけど、チェックリストとしてはこれくらい合って良いと思う。

❐ URIが短く入力しやすくなっているか
❐ URIが人間が読んで理解できるようになっているか
❐ URIが小文字のみで構成されているか
❐ URIが改造しやすくなっているか
❐ URIにサーバ側のアーキテクチャが反映されていないか
❐ URIのルールは統一されているか
❐ 適切なHTTPメソッドを利用しているか
❐ URIで利用する単語は多くのAPIで同じ意味に利用されているものを選んでいるか
❐ URIで使われている名詞は複数形になっているか
❐ URI中にスペースやエンコードを必要とする文字が入っていないか
❐ URI中の単語はハイフンでつないでいるか
❐ ページネーションは適切に設計されているか
❐ ログインにはOAuth 2.0を利用しているか
❐ レスポンスのデータ形式はJSONがデフォルトになっているか
❐ データ形式の指定にはクエリパラメータを使う方法をサポートしているか
❐ 不要なJSONPに対応していないか
❐ レスポンスのデータ内容はクライアントから指定できるようになっているか
❐ レスポンスデータに不要なエンベロープが入っていないか
❐ レスポンスデータの構造は可能なかぎりフラットになっているか
❐ レスポンスデータが配列ではなくオブジェクトになっているか
❐ レスポンスのデータ名として多くのAPIで同じ意味に利用されている一般的な単語を選んでいるか
❐ レスポンスのデータ名はなるべく少ない単語数で表現しているか
❐ レスポンスのデータ名として複数の単語を連結する場合、その連結方法はAPI全体を通して統一してあるか
❐ レスポンスのデータ名として変な省略形を使用していないか
❐ レスポンスのデータ名の単数系/複数形はデータの内容と合っているか
❐ エラー時のレスポンスはクライアントが原因を切り分けられるような情報を含んでいるか
❐ エラーの際にHTMLが返っていないか
❐ 適切なステータスコードが返るようになっているか
❐ メンテナンス時には503を返しているか
❐ 適切なメディアタイプを返しているか
❐ 必要な場合はCORSに対応しているか
❐ クライアントが適切にキャッシュを行えるようにCache-Control、Etag、Last-Modified、Varyなどのレスポンスヘッダを返しているか
❐ APIはバージョン管理されているか
❐ APIのバージョンはセマンティックバージョニングに沿ったものになっているか
❐ メジャーバージョン番号がURIに入っており、一目でわかるようになっているか
❐ APIの提供を終了する際のことを考慮に入れているか
❐ APIの最低提供期間をドキュメントに明記しているか
❐ HTTPSでAPIを提供しているか
❐ JSONのエスケープを行っているか
❐ JSONはX-Requested-withヘッダを認識するなど、SCRIPT要素では読み込めないようになっているか
❐ ブラウザからアクセスできるAPIではXSRFトークンを利用しているか
❐ APIが受け取るパラメータはきちんと不正値(マイナスの値など)をチェックしているか
❐ リクエストが再送信されてもデータを再度更新してしまわないようになっているか
❐ レスポンスにセキュリティ対策用の各種ヘッダをつけているか
❐ レートリミットによる制限を行っているか
❐ レートリミットの精度回数は想定されるユースケースに対して少なすぎないか

おわりに

「Web API: The Good Parts」についてまとめました。

参考記事

Web API: The Good Parts