Web API: The Good Parts

1章 Web API とは何か

Web API を公開していないなら、すぐにその公開を検討する
- API は、いわばほかのサービスとの接着剤。
- 公開することで、その API とほかのものを組み合わせて、よりよいものを作ってくれる人が出てくる可能性がある。
- リスクはほぼない。API を使って悪さをしようとする人は、API がなくてもあらゆる手段を講じて悪さをする。
Web API を美しく設計する
- 使いやすく、変更しやすく、頑強で、恥ずかしくない設計にする。
- LSUDs (large set of unknown developers) 向けなのか SSKDs (small set of known developers) 向けなのかを考える。どちら向けなのかによって、「美しさ」の定義が変わってくる。
REST という言葉にこだわりすぎない
- Roy Fielding の言う REST なのか、それとももうちょっとゆるい REST なのか、みたいな議論が勃発するため。
- REST という言葉を使うことで混乱を招く可能性もある。

覚えやすく、どんな機能を持つかが一目でわかるエンドポイントにする
- 短く入力しやすい
- 人間が読んで理解できる
- 小文字に統一されている
- サーバ側のアーキテクチャが隠蔽されている
- ルールが統一されている
適切な HTTP メソッドを利用する
- POST とか GET とか。RFC を読めばよい。
適切な英単語を利用し、単数形、複数形にも注意する
- 基本的に複数形。適切な英単語の選び方としては、世の中の類似の API を調べて標準的な命名を調べてがんばる。
SSKDs と API デザイン
- 1スクリーン1 API コールという指針。速度の問題の抑制だけでなくデータの整合性等も守りやすくなる。”Chatty” な API 設計は避ける。
HATEOAS と REST API
- REST LEVEL0: HTTP を利用している
- REST LEVEL1: リソースの概念の導入
- REST LEVEL2: HTTP メソッドの適切な利用の導入
- REST LEVEL3: HATEOAS の概念の導入
  - リンクによって複数のメディアを結ぶ。返すデータの中に、続いて情報を取得するための URL を含める、など。
認証には OAuth 2.0 を使う

JSON、あるいは目的に応じたデータ形式を採用する
- 返却するデータを必要最小限にするためにレスポンスグループの導入を検討してもよい。cf) Amazon の Product Advertising API
データを不要なエンベロープで包まない
- HTTP というプロトコル自体が通信で用いるエンベロープみたいなものなので、pyaload の中でさらにエンベロープを利用する意味はあんまりない。
- JSONP を利用している場合はエンベロープ的なものを利用した方が便利ということもある。
レスポンスをできるかぎりフラットな構造にする
- ネストしないと namespace がぶつかりまくって prefix をつけまくらなきゃならない、というのは望ましくないので、そういう場合はネストしていい。
- 単に複数の項目をひとつの object にまとめたいから、というだけの動機なら、フラットにした方がよい。
各データの名前が簡潔で理解しやすく、適切な単数複数が用いられている
エラーの形式を統一し、クライアント側でエラー詳細を機械的に理解可能にする
注意点
- でかい数字は JqvaScript で浮動小数点誤差出る可能性あるので気を付ける。
- DB のテーブル構造をそのまま反映したような形にはしない。

HTTP の仕様を最大限利用し、独自仕様の利用を最低限にとどめる
- RFC よもうね。
- CORS (cross-origin resource sharing) を利用する。アクセス元のホワイトリストみたいな感じの仕組み。
適切なステータスコードを用いる
- RFC よもうね。
適切な、なるべく一般的なメディアタイプを返す
クライアントが適切なキャッシュを行えるように情報を返す
- Expiration Model, Validation Model, Heuristic Expiration など。
- キャッシュさせないという選択肢も必要ならする。
- Vary でキャッシュの単位を指定する。

個人情報など特定のユーザ以外に漏洩したくない情報がある場合は HTTPS を使う
- 暗号化によって盗聴を防ぐ。
- 認証によってなりすましを防ぐ。
- とはいえそれだけじゃ完璧じゃなくて、セッションハイジャックとかの中間者攻撃のリスクは残る。
XSS、XSRF など通常のウェブと同様のセキュリティだけでなく JSON ハイジャックなど API 特有の脆弱性に気を配る
- ゲームでのチート行為、パラメータ改ざん、など。
セキュリティ強化につながる HTTP ヘッダをきちんとつける
- X-Content-Type-Options/X-XSS-Protection/X-Frame-Options/Content-Security-Policy/Strict-Transport-Security/Public-Key-Pins/Set-Cookie
レートリミットを設けることで一部のユーザによる過度のアクセスによる負荷を防ぐ
- いわゆる DoS 攻撃対策