Web API The Good Partsの読書メモの後編である。前編はこちら。
４．レスポンス形式
4.1 データの形式について
リクエスト・レスポンスで渡すデータの形式は今はJSONがデフォルトである。ゆえにJSONを基本とし、必要に応じてXMLにも対応するという指針で行く。
データのフォーマットの指定方法はいろいろあるが、クエリパラメータで指定するのが望ましい。例えばXMLで受け取りたい場合は、?format=XMLなどと指定する。
4.2 レスポンスデータの設計指針
レスポンスデータの構造を考えるとき、以下のような方針で設計するとよい。
- API のアクセス回数がなるべく減るようにする
- 何度もアクセスが発生するような設計は避けること
- ユースケースをよく考えるのが大切
- レスポンスの内容をユーザが選べるようにする
- 取得する項目を利用者が選択可能にする → fieldsクエリで指定するなど
- いくつかのパターンを提供する
- なるべくフラットな構造（平面、つまりは属性がすべて同じレベルにある）にする
- オブジェクトに統一する
- 配列もオブジェクトに包む → friends:[配列]の形
- データの続きの有無（あるいは件数）をよく考える
- データ全体を返す必要があるのか考える → 件数は情報として必要なのか？
- hasNext:などでデータに続きがあることを表す
- 次の要素への相対位置を渡してもよい
4.3 レスポンスデータの項目名称と形式
- データの名前のポイント
- 多くのAPI で利用されている同じ意味の一般的な単語を用いる
- なるべく少ない単語数で表現する
- 複数の単語を連結する場合、その連結方法はAPI 全体を通して統一する
- 変な省略形は極力利用しない
- 単数形／複数形に気をつける
- 性別の形式
- 生物学的:sex
- それ以外:gender
- 男、女以外ではないため、文字列形式が無難
- 日付のフォーマット
- 大きな数の表現
- 別の項目名で文字列としても表現する
- 64ビットの数はJavascriptでは浮動小数点数として扱うため誤差が生じる
4.4 エラーの表現について
- HTTPステータスコードでエラーを表現
- クライアント側のエラーは400
- サーバ側のエラーは500
- エラーで200は返さないこと
- エラーの詳細
- レスポンスボディに入れる
- エラーの際にHTMLが返ることを防ぐ
- 500,503,404などWebサーバの設定がデフォルトになっている場合はHTMLが返る
- メンテナンス時は503
- 計画的なものならばRetry-Afterヘッダの値も返すのが適切
4.5 返却するHTTPステータスに迷ったら
本とは無関係だが以下のサイトが参考になる。
５．APIのライフサイクル設計
ここではAPIのバージョン管理のポイントを記す。
- URIにバージョンを埋め込む
- URIのパスの先頭に付ける v{数字}
- メジャーバージョン番号のみで可
- セマンティックバージョニング
- {メジャー番号}.{マイナー番号}.{パッチ番号}
- バージョンアップの指針
- 後方互換を保てないような修正をする時に上げる
- パラメータの型変更などは廃止予定とし、代替のパラメータを用意することでいきなりなくさない
- API提供の終了
６．セキュリティ指針
6.1 セキュリティを考慮した設計とは
ポイントを以下に示す。
- ブラウザがJSONをJSON と必ず認識するようにする
- リクエストヘッダチェックを活用する
- 通常のブラウザ操作では送信されないリクエストヘッダの有無をサーバ側でチェックする
- ヘッダがある時のみ応答を返す
- 例：X-Requested-With: XMLHttpRequest 等
- JSON をJavaScript として解釈不可能、あるいは実行時にデータを読み込めないようにす る
ところでセキュリティの話自体は『体系的に学ぶ安全なWebアプリケーションの作り方』という良書があるため本格的にセキュリティを学ぶならばそちらを見た方がよい。ちなみに当ブログでも読書メモの記事を書いたことがあるので本に関心があるのであればチラ見して欲しい。
6.2 大量アクセス対策
アクセスは無制限に許可するわけにもいかない。対処の指針を以下に示す。
- ユーザ毎のアクセス数の制限
- 単位時間あたりの最大アクセス数（レートリミット）を設ける
- 検討事項
- 何を使ってユーザーを識別するか
- リミット値をいくつにするか
- どういう単位でリミット値を設定するか
- リミットのリセットをどういうタイミングで行うか
- レートリミットオーバ時の応答
- 429 Too Many Requests
- エラー詳細を応答に含める
- Retry-Afterでどれくらい待てばいいのかを指定することが可能 → 秒数、もしくは具体的な日付の指定
- 429 Too Many Requests
- レートリミットの値を返す
参考文献
- 作者: 水野貴明
- 出版社/メーカー: オライリージャパン
- 発売日: 2014/11/21
- メディア: 大型本
- この商品を含むブログ (7件) を見る
