はじめに
- 前回、API関連の調査をしているので、引き続き気になる点を調査してみる px-wing.hatenablog.com px-wing.hatenablog.com
レスポンス データフォーマット
| フォーマット | 概要 | 注意点 |
|---|---|---|
| XML | XMLは、個別の目的に応じたマークアップ言語群を創るために汎用的に使える。 <要素名 属性="値">内容</要素名> |
|
| JSON | JavaScript Object Notation - JSONで表現するデータ型は以下の通り。 1.オブジェクト（順序づけされていないキーと値のペアの集まり。JSONでは連想配列と等価） 2.配列（データのシーケンス） 3.数値（整数、浮動小数点数） 4.文字列（バックスラッシュによるエスケープシーケンス記法を含む、ダブルクォーテーション"でくくった文字列） 5.真偽値（true と false） 6.null |
|
| JSONP | JSON with padding scriptタグを使用してクロスドメインな（異なるドメインに存在する）データを取得する仕組みのことである。HTMLのscriptタグ、JavaScript（関数）、JSONを組み合わせて実現される。 |
クロスサイトリクエストフォージェリ（CSRF）に対する脆弱性に注意が必要である。 |
レスポンス フォーマットリクエスト方法
| フォーマット | サンプル |
|---|---|
| クエリパラメータ | http://api.sample.com/v1/users?format=json |
| 拡張子 | http://api.sample.com/v1/users.json |
| リクエストヘッダー | GET http://api.sample.com/v1/users Host: api.sample.com Accept: application/json |
レスポンスデータの内部構造の設計で考慮すること
| ポイント | 概要 |
|---|---|
| エンベロープは使わない | ヘッダー情報と役割が被るので、エンベロープは使わない |
| オブジェクトはできるだけフラットにする | JSONはネストした構造を作成することができるが、レスポンス容量を減らす。クライアント側のPerthする処理を軽減するためにも、オブジェクトはできるだけフラットにする |
| ページネーションをサポートする情報は返さない | 情報更新される可能性があるため。 {"users": [ { "id" : "12345", "name" : "Yamada Taro" } ], "nextPage" : 3, "prevPage": 1 } {"users": [ { "id" : "12345", "name" : "Yamada Taro" } ], "hasNext" : true } |
| プロパティの命名規則はAPI全体で統一する | - スネークケースまたはキャメルケースのどちらかで統一する - JSONがJavaScriptベースであるおとプロパティ名は変数名に相当するととらえるならキャメルケースが妥当 |
| 日付はRFC3339(W3C-DTF) 形式を使う | 「2020-09-02T09:33:12+09:00」 |
| 大きな数値（64bit整数）は文字列を返す | - javascriptで扱える演算可能な歳男性数は「9,007,199,254,740,991」 |
エラー処理の考慮
| ポイント | 概要 |
|---|---|
| - エラー詳細はレスポンスボディに入れる。ステータスコードだけで判断しない |
{ "code": "12345", "message" : 不正な検索条件です } |
| - エラーの際にHTMLが返らないようにする |
クライアント側はJSON形式などを受け取る想定でいるので、レスポンスフォーマットが変わること。クライアントアプリ側で処理できないため。 Content-Type: application/json { "code": "12345", "message" : 不正な検索条件です } |
| サービス閉塞時は503 + "Retry-After"で返す | Content-Type: application/json Retry-After: Mon, 6 Apr 2020 ・・・ { "code": "9999", "message" : "サービスは利用できません" } https://developer.mozilla.org/ja/docs/Web/HTTP/Headers/Retry-After |
