読者です 読者をやめる 読者になる 読者になる

Jの衝動書き日記

さらりーまんSEの日記でございます。

Web API The Good Partsの読書メモ(後編)

Web 技術

 Web API The Good Partsの読書メモの後編である。前編はこちら。

4.レスポンス形式

4.1 データの形式について

 リクエスト・レスポンスで渡すデータの形式は今はJSONがデフォルトである。ゆえにJSONを基本とし、必要に応じてXMLにも対応するという指針で行く。

 データのフォーマットの指定方法はいろいろあるが、クエリパラメータで指定するのが望ましい。例えばXMLで受け取りたい場合は、?format=XMLなどと指定する。

4.2  レスポンスデータの設計指針

 レスポンスデータの構造を考えるとき、以下のような方針で設計するとよい。

  • API のアクセス回数がなるべく減るようにする
    • 何度もアクセスが発生するような設計は避けること
  • レスポンスの内容をユーザが選べるようにする
    • 取得する項目を利用者が選択可能にする → fieldsクエリで指定するなど
    • いくつかのパターンを提供する
  • なるべくフラットな構造(平面、つまりは属性がすべて同じレベルにある)にする
  • オブジェクトに統一する
    • 配列もオブジェクトに包む → friends:[配列]の形
  • データの続きの有無(あるいは件数)をよく考える
    • データ全体を返す必要があるのか考える → 件数は情報として必要なのか?
    • hasNext:などでデータに続きがあることを表す
    • 次の要素への相対位置を渡してもよい
4.3  レスポンスデータの項目名称と形式
  • データの名前のポイント
    • 多くのAPI で利用されている同じ意味の一般的な単語を用いる
    • なるべく少ない単語数で表現する
    • 複数の単語を連結する場合、その連結方法はAPI 全体を通して統一する
    • 変な省略形は極力利用しない
    • 単数形/複数形に気をつける
  • 性別の形式
    • 生物学的:sex
    • それ以外:gender
    • 男、女以外ではないため、文字列形式が無難
  • 日付のフォーマット
    • 基本はRFC 3339
      • 2015-10-12T11:30:22+00:00 ※タイムゾーンUTCなので+00:00を使う
      • ただし、HTTPヘッダの形式はこれではないので注意
  • 大きな数の表現
    • 別の項目名で文字列としても表現する
    • 64ビットの数はJavascriptでは浮動小数点数として扱うため誤差が生じる
4.4 エラーの表現について
  • HTTPステータスコードでエラーを表現
    • クライアント側のエラーは400
    • サーバ側のエラーは500
    • エラーで200は返さないこと
  • エラーの詳細
    • レスポンスボディに入れる
  • エラーの際にHTMLが返ることを防ぐ
    • 500,503,404などWebサーバの設定がデフォルトになっている場合はHTMLが返る
  • メンテナンス時は503
    • 計画的なものならばRetry-Afterヘッダの値も返すのが適切
4.5 返却するHTTPステータスに迷ったら

 本とは無関係だが以下のサイトが参考になる。

 

postd.cc

 

5.APIのライフサイクル設計

 ここではAPIのバージョン管理のポイントを記す。

  • URIにバージョンを埋め込む
    • URIのパスの先頭に付ける v{数字}
    • メジャーバージョン番号のみで可
  • セマンティックバージョニング
    • {メジャー番号}.{マイナー番号}.{パッチ番号}
      • メジャー番号:後方互換性のない変更が行われた際に増える
      • マイナー番号:後方互換性のある機能変更、あるいは特定の機能が今後廃止されることが決まった場合に増える
      • パッチ番号:ソフトウェアのAPI に変更がないバグ修正などを行ったときに増える
  • バージョンアップの指針
    • 後方互換を保てないような修正をする時に上げる
    • パラメータの型変更などは廃止予定とし、代替のパラメータを用意することでいきなりなくさない
  • API提供の終了
    • 予め提供終了時の仕様を盛り込んでおく
      • 410 Goneを返すようにする
      • 410 が返った場合は公開が終了したことを意味する旨を明記
      • スマートフォンアプリ等は強制アップデートの仕組みを入れておく
      • サポート切れのAPIを使用している場合はバージョンアップを促す

 

6.セキュリティ指針

6.1 セキュリティを考慮した設計とは

 ポイントを以下に示す。

  • ブラウザがJSONJSON と必ず認識するようにする
    • メディアタイプはapplication/jsonにする
    • X-Content-Type-Options: nosniff も設定する → IEのコンテンツ自動解釈を無効にする
  • リクエストヘッダチェックを活用する
    • 通常のブラウザ操作では送信されないリクエストヘッダの有無をサーバ側でチェックする
    • ヘッダがある時のみ応答を返す
    • 例:X-Requested-With: XMLHttpRequest
  • JSONJavaScript として解釈不可能、あるいは実行時にデータを読み込めないようにす る
    • エスケープ処理を適切に行う
    • 配列ではなく、オブジェクトを返す
    • JSON無限ループという手もある
      • JSONデータの先頭に無限ループを仕込み、SCRIPT要素に読み込まれるのを回避する
      • JSONデータとして使う場合は、予め除去する

 ところでセキュリティの話自体は『体系的に学ぶ安全なWebアプリケーションの作り方』という良書があるため本格的にセキュリティを学ぶならばそちらを見た方がよい。ちなみに当ブログでも読書メモの記事を書いたことがあるので本に関心があるのであればチラ見して欲しい。

 セキュリティ カテゴリーの記事一覧 - Jの衝動書き日記

 

6.2  大量アクセス対策

 アクセスは無制限に許可するわけにもいかない。対処の指針を以下に示す。

  • ユーザ毎のアクセス数の制限
    • 単位時間あたりの最大アクセス数(レートリミット)を設ける
    • 検討事項
      • 何を使ってユーザーを識別するか
      • リミット値をいくつにするか
      • どういう単位でリミット値を設定するか
      • リミットのリセットをどういうタイミングで行うか
  • レートリミットオーバ時の応答
    • 429 Too Many Requests
      • エラー詳細を応答に含める
      • Retry-Afterでどれくらい待てばいいのかを指定することが可能 → 秒数、もしくは具体的な日付の指定
  • レートリミットの値を返す
    • HTTP のレスポンス
      • X-RateLimit-Limit : 単位時間あたりのアクセス上限
      • X-RateLimit-Remaining : アクセスできる残り回数
      • X-RateLimit-Reset : アクセス数がリセットされるタイミング
        • 値はリセットされるタイミングまでの秒数と、リセットされる時間を表すUnix タイムスタンプ(エポック秒
        • UnixタイムスタンプはHTTPヘッダの仕様定義上では本来NG → 時刻表示ならばOK

 参考文献

Web API: The Good Parts

Web API: The Good Parts