https://www.oreilly.co.jp/books/9784873116860/
📝 2014年の話であることに注意
そのサービスのコアの価値のある部分をすべて利用可能にするべき
📝 最初から全公開を目指さず利用ケースを想定して順に
- 使いやすい
- 変更しやすい
- 頑強
- 恥ずかしくない
- 仕様が決まっているものに関しては仕様に従う
- 仕様が存在していないものに関してはデファクトスタンダードに従う
📝 逸脱した設計にしないのはソースコードも一緒
📝 利用者が戸惑わない(類推可能)
- LSUDs(large set of unknown developers)
- パブリックにAPIをドキュメントともに公開し、誰でもが登録して使えるようにしたもの
- パブリックにAPIをドキュメントともに公開し、誰でもが登録して使えるようにしたもの
- SSKDs(small set of known developers)
- APIを利用する開発者が限られている
- 自社サービスのスマートフォンクライアント向けのAPI
- APIを利用する開発者が限られている
3.1.1 データフォーマットの指定方法
- クエリパラメータ
- 拡張子
- リクエストヘッダでメディアタイプを指定
3.3.5 配列の件数、あるいは続きがあるかをどう返すべきか
- 件数をレスポンスに含める
- N+1 件を取得する
- hasNext のような「次があるのか」を返す
性別 : sex or gender
サービスの特性に合わせて
ヘッダー情報で表現できるが body で返すのがわかりやすい
エラー詳細情報をどこまで返すか
エラーが HTML になってしまわないように
3.6.5 メンテナンスとステータスコード
HTTP STATUS 503
Retry-After HTTP ヘッダを使っているメンテナンスが終わるのかを示す
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.1 Expiration Model
- Expires
- Cache-Control