- WebAPI The Good Parts
- 真新しい内容はないけどなんとなくでやりがちな部分に答えを出しているのがよかった。
- WebAPIを作ったことはあるけど本気で設計を考えたことなかった、みたいな人にはいい一冊だと思った。
URLについて
- URLに大文字や小文字を混在させるべきではない
- 単語を繋げなくては行けない場合はハイフンがいい
- 個人的には_が一般的だと思うんだけど・・・・
- パラメータやフィールド名で迷ったら、http://www.programmableweb.com/ で似たような事例の単語に合わせるほうが無難
- searchという単語
- リストの一機能として絞込を提供するならsearchというエンドポイントで切る必要はないね（リストに絞込機能をもたせればいいね）
- リストは全部返す、検索用はあくまでこれ、という立て付けであればsearchAPIを設けるべき
- 検索に find という単語は使わないのが一般になってる
- 相対位置指定と絶対位置指定
- 相対位置指定＝pageとnumber指定のタイプ
- 絶対位置指定＝ID:xxx以降の20件取得,timestamp:XXX以降の20件、など
- 絶対位置指定なら検索中に投稿されてもズレが生じない
- OAuth2.0認証つきのAPIで自分のリソースへのアクセスについて
- いちいち自分のidを取得するステップを踏ませてしまうのではなく、meやselfという文字列を指定するようにするAPIが多い
LSUDs SSKDs
-
LSUDsとSSKDs
- LSUDs = Large set of unknown developers
- 不特定の開発者たちに叩かれるAPIのことを指す
- SSKDs = Small set of known developers
- 開発者が身内でしかない、身内にしか公開しないAPIのことを指す
- LSUDsは汎用的に、SSKDsはもっとクライアント寄りに設計する
-
オーケストレーション
- LSUDs→SSKDsへの変換
- クライアントとWebAPI間に置く
- WebAPIへリクエストし、各クライアントへ最適化したAPIを提供する
- オーケストレーション層の開発者＝アプリ（クライアント）の開発者
- Netflixが発表して浸透している考え方
Hypermedia API
- HATEOAS（hypermedia as the engine of application state）
- マーティン・ファウラーの提唱するREST LEVEL3における考え方
- ハイパーテキストをリンクでつないだもの＝ハイパーメディア
- APIで操作するリソースにも同じ考えを導入したもの
- 次にユーザが取る行動をリンクとしてレスポンスに含める
- たとえばユーザ一覧を返すAPIのリンクには各ユーザの詳細が引けるAPIへのリンクを含める、など
- クライアントが予めエンドポイントを知らなくてもAPIが叩ける
- 人間がサイトをたどっていくのと同じ
- 返ってきたリソースが何なのか、はメディアタイプを使って返している
- HAL
- エンベロープは不要
- httpのセマンティクスに乗っているから
- jsonトップレベルを配列にして返さないほうがよい
- トップレベルをオブジェクトで包めば配列にkey(名前)がつけられるので内容がわかりやすくなる
- メンテナンスは Retry-After ヘッダ
- キャッシュはHTTPキャッシュ RFC7234を使うのもよい
- ヘッダで時刻を表現する場合はRFC1123を使うこと
- Last-Modified、ETag
- クロスオリジンリソース共有 CORS
- IE8,9は非対応
バージョニング
- URIのパスでバージョニングが一般的
- メディアタイプでバージョニング
- githubなど
- 日付でバージョニングは古くて冗長で流行ってない
- パラメータでバージョニングだと指定ない場合のバージョンが明確ではない
- BlackOutTest
- 旧バージョンのAPIを廃止する際に一時的に落としてテストする
セキュリティ
- XSRF対策
- 状態を変えるAPIはGETを使わない
- ワンタイムトークンを使う
- JSONハイジャック
- scriptタグは同一生成元ポリシーが有効ではない