Web API: The Good Parts読んだ

何の本？

Web APIの設計、開発、運用についての解説書。APIは設計次第で使いづらいものになってしまうだけでなく公開後の保守運用も難しくなってしまいます。そのためAPIを美しく設計することがとても重要です。本書では「設計の美しいAPIは、使いやすい、変更しやすい、頑強である、恥ずかしくない」という考えのもと、APIをどのように設計し運用すればより効果的なのか、ありがちな罠や落とし穴を避けるにはどういう点に気をつけなければいけないのかを明らかにします。ターゲットは、URIにアクセスするとXMLやJSONなどのデータが返ってくるシンプルなタイプ――XML over HTTP方式やJSON over HTTP方式――のAPIです。読者は、Web API設計の考え方と手法を知ることができます。

引用元-oreilly

ウェブAPIについて、その中でもHTTPでエンドポイントにアクセスすることでJSONを返すAPIの設計について書かれている。

よかったこと

APIに関する基礎知識を身につけることができた。
APIの設計というと、エンドポイントの設計やレスポンスデータの設計ばかりをイメージしていたが、HTTPヘッダなどをどのように設定すべきであるのか等、セキュリティの観点からの実装などが特に参考になった。

美しいAPIを設計するポイント

• 仕様が決定しているものについては仕様に従う
• そうでないものについて、デファクトスタンダードが存在している場合にはそれに従う

エンドポイントの設計

• エンドポイントについて覚えやすく、それがどんなものなのか一目でわかる
• GETの安定性？を損なわない　GETで何かの更新や、削除を行わない（WEB技術にも記載があった）

レスポンスデータの設計

• 取得数と取得位置のクエリパラメータを返す際に、取得位置を相対位置にするとずれる
• レスポンスデータの設計では、どのような情報をどう返すのかを設計する。
• 例えば友達一覧であれば、友達のどの情報を返すのか？　何度もアクセスしなければならないAPIはchatty APIと呼ばれ、利用者の手間を増やし、トラフィックを増加させ、いいことが何もない。。
• WEBAPIは単なるデータベースのアクセスインターフェイスではなくアプリケーションのインターフェイスであるべきであるから、アプリケーションの特性を踏まえた利用者が利用しやすい設計が必要。
• レスポンスグループの利用も有効的
• 続きがあるときはhasnext: true にしたり、次のページを取得するためのトークンやURIを指定したりして続きをとりやすいようにしてあげる

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

• HTTPレスポンスのステータスコードは適切なものを選ぶ
• メディアタイプはapplivation/jsonで返す 自分で新しいメディアタイプを指定して返すこともできる

キャッシュの必要性

• キャッシュできるものはキャッシュしてサーバの負担を減らしつつ、最新のものが出たらちゃんと更新させる
• キャッシュにはValidation Model（検証モデル）とHeuristic Expiration（発見的期限切れ）があり、検証モデルでは現状のキャッシュが有効かどうか確認するリクエストを送り、更新されていたときにのみデータを返し、更新の必要がないときは304を返す。このとき、Last-ModifiedとEtagというレスポンスヘッダを用いて返される。
• 発見的期限切れにおいてはサーバ側が明確な期限を与えなかった場合に、クライアントがキャッシュの期限を自分で決める。基本的にはChache-controlやExpiresなどを用いてキャッシュの期限を返してあげるべきである。
• Cache-Controlヘッダにおいて、privateに指定されたものはクライアントのみがキャッシュでき、CDNやプロキシのような仲介エージェントはキャッシュできないが、反対に逆にpublicにおいてはキャッシュをプロキシにおいて異なるユーザ間で共有することができる。
• no-storeにおいてはキャッシュは禁止され、no-cacheにおいては毎回Etagを利用してバージョンの更新がないかを確認しなければならない。
• EtagはApacheにおいてはサーバーが２台ある場合にはそれぞれ同じバージョンにおいても別のEtagが生成されてしまうため、キャッシュがうまく働かなくなってしまうことがある。（参考のURLを参照）

最初に述べられているように、仕様やデファクトスタンダードに則った利用しやすいAPIを構築するためのノウハウが、HTTPそのものの仕様にも触れられながら分かりやすく記載されていて、知識を整理することに役立った。ユースケースを想定してものを作ることが設計の基礎なのだということがとてもよくわかった。巻末にAPI設計時のチェックリストが記載されているので、参考にしたい。

今後ちゃんと調べたいところ

OAuthによる認証の詳細
キャッシュの構造、とくにメモリーやディスクに保存される場合の挙動

参考