Web API: The Good Parts / Note

web-api-the-good-parts-note.md

https://www.oreilly.co.jp/books/9784873116860/

📝 2014年の話であることに注意

1. Web API とは何か

1.3 何をAPIで公開すべきか

そのサービスのコアの価値のある部分をすべて利用可能にするべき

📝 最初から全公開を目指さず利用ケースを想定して順に

1.4 Web APIを美しく設計する重要性

• 使いやすい
• 変更しやすい
• 頑強
• 恥ずかしくない

1.5 Web APIを美しく設計するには

• 仕様が決まっているものに関しては仕様に従う
• 仕様が存在していないものに関してはデファクトスタンダードに従う

📝 逸脱した設計にしないのはソースコードも一緒
📝 利用者が戸惑わない（類推可能）

1.7 対象となる開発者の数とAPIの設計思想

• LSUDs（large set of unknown developers)
  • パブリックにAPIをドキュメントともに公開し、誰でもが登録して使えるようにしたもの
    • Facebook
    • Twitter
• SSKDs（small set of known developers）
  • APIを利用する開発者が限られている
    • 自社サービスのスマートフォンクライアント向けのAPI

2. エンドポイントの設定とリクエストの形式

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

3.1

3.1.1 データフォーマットの指定方法

• クエリパラメータ
• 拡張子
• リクエストヘッダでメディアタイプを指定

3.3

3.3.5 配列の件数、あるいは続きがあるかをどう返すべきか

• 件数をレスポンスに含める
• N+1 件を取得する
• hasNext のような「次があるのか」を返す

3.4 各データのフォーマット

性別 : sex or gender
サービスの特性に合わせて

3.6 エラーの表現

ヘッダー情報で表現できるが body で返すのがわかりやすい
エラー詳細情報をどこまで返すか
エラーが HTML になってしまわないように

3.6.5 メンテナンスとステータスコード

HTTP STATUS 503
Retry-After HTTP ヘッダを使っているメンテナンスが終わるのかを示す

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

4.2

4.2.1 200 番台

202 Accepted : 非同期で行われ、処理は受け付けたが完了していない場合

• LinkedIn -> モデレータの承認を必要とする場合。すぐに投稿が表示されないケース（広い意味で非同期）
• Box -> DLするファイルがまだ準備中の場合。所要時間を Retry-After ヘッダで返す

204 No Content

• PUT や PATCH の場合は 200 とともに操作したデータを返し
• DELETE の場合は 204 を使う（筆者の見解）

📝 👍

4.2.2 300番台

RFC2616
303 -> リダイレクト前のメソッドによらず、 GET を使ってアクセスを行うもの
実際は 302 を使ってリダイレクトしているケースが多い

4.2.3. 400番台

410 Gone
メアドによるユーザー検索など個人情報を扱うところでは注意

429 Too Many Requests

4.3 キャッシュとHTTPの仕様

4.3.1 Expiration Model

• Expires
• Cache-Control

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

6.堅牢なWeb APIを作る