読書記録【Web API The Good Parts】
概要
Web APIを作成する際のお約束ごとがまとめられた書籍です。 これからAPIを作り始める方やチームでAPI開発が始まるタイミングで読むのにおすすめの内容になっています。
1章 Web APIとは何か
REST API とは
・HTTPメソッドで処理の目的を識別する
・ステートレスであること（べき関数 1回やっても、100回やっても同じ。誰がやっても同じ）
・ステータスコードを返却すること
https://www.subthread.co.jp/blog/20160506/
https://qiita.com/masato44gm/items/dffb8281536ad321fb08
https://blog.api.rakuten.net/ja/jp-restful-api/
２章 エンドポイントの設計とリクエストの形式
モバイルアプリケーション向けAPIに必要な機能
まず、アプリケーションの画面とその遷移を考える
- 処理を洗い出して、エンドポイントを決めていく
- 列挙した処理を全て実装するのではなく、まとめられるものは無いか検討する
適切なHTTPメソッドを利用すること
エンドポイント設計の注意点
・複数形の名詞を利用する
・利用する単語に気を付ける
・スペースやエンコードを必要とする文字を使わない
・単語を繋げる必要がある場合はハイフンを利用する
自分の情報へのエイリアス
・自身の情報にアクセスするには必ず認証処理が行われるはずなので、リソースにユーザーIDを利用する必要は無い。
- 間違えて他人の情報が見えてしまう、というバグが混入するきっかけになる
３章 レスポンスデータの設計
エンベロープは必要か
エンベロープとは
メタデータ、ヘッダー情報も含んだような形で全てのAPIが同じデータ構造を返すために実際のデータをくるむための構造
- header情報はHTTPヘッダに含めるだけで十分なので、エンベロープは不要である
データはフラットにすべきか
階層構造にしてデータを返却することにメリットが無い場合は、フラットにしておくべき
階層構造にさせることでメリットがある場合にのみ階層化すること
配列とフォーマット
オブジェクトに内包すること
・レスポンスデータが何を示しているものかがわかりやすくなる
・レスポンスデータをオブジェクトに統一することができる
・セキュリティ上のリスクを避けることができる（JSONインジェクションの防止）
エラー詳細情報には何を入れるべきか
・開発者向けのメッセージ
・ユーザ向けのエラーメッセージ
・レスポンスコード
・追加情報
4章 HTTPの仕様を最大限利用する
利用する意義
・独自仕様の混入を防ぐ
・利用者にとっても、理解しやすく、利用時のバグ混入を減らす事ができる
・ライブラリやコードが再利用可能になる可能性が高くなる
204コードについて
PUTやPATCHメソッドでのデータ更新は既存データの更新だけなので204を返すのが自然という意見もある。
筆者の見解では、
PUTやPTACHの場合は、200とともに操作したデータを返却する事がベターとのこと。
- データ変更後の成否が判断できるため。
- DELETEの場合は204を返す
ざっくりと以下の理解で記憶しておく
200番台 成功
300番台 追加で処理が必要
400番台 クライアントのリクエストに問題があった場合
500番台 サーバーに問題があった場合
キャッシュ
期限切れモデルの使い所
・特定の日時に更新されることが予めわかっている場合
・今後更新される可能性がないデータや静的データの場合
検証モデルの使い所
・期限切れモデル対象に含まれず、キャッシュ効果の高いデータの場合
- 都度データ更新を検証する必要はあるがキャッシュせずに全てのデータを取ってくるよりも、更新がない場合に返ってくるデータが304ステータスコードだけになるので、レスポンスは断然早い
キャッシュさせたくない場合
HTTPヘッダにCache-Control: no-cacheを追加してあげる
メディアタイプ
メディアタイプを正しく設定してあげないと、正常に動作しないことが発生する
Chromeで動いても、Safari、FireFoxで動かないケースもあるので設定すること
５章 設計変更しやすいWeb APIを作る
・APIバージョンの更新は最低限にとどめ、後方互換性にも注意する
・APIのバージョンはメジャーバージョンをURIに含める
・APIの提供終了後はすぐに終了するのではなく最低6ヶ月公開を続ける
６章 堅牢なWebAPIを作る
・個人情報など特定のユーザ以外に漏洩したくない情報がある場合はHTTPSを使う
・XSS,XSRFなど通常のウェブと同様のセキュリティだけでなくJSONハイジャックなどAPI特有の脆弱性に気を配る
・セキュリティ強化につなげるHTTPヘッダをきちんと付ける
・レートリミットを設けることで一部のユーザーによる過度のアクセスによる負荷を防ぐ
まとめ
APIを多くの人に安全に開発、利用してもらうためのノウハウが詰まった本になっておりました。 API開発する度にこの本を読み直して、最適なAPI設計していけるようにしていきたいですね！
