APIを利用する側にレスポンスとしてどのようなデータを返却するかを検討する。
レスポンスデータを設計する上での考え方
APIのレスポンスデータはほとんどの場合プログラムで処理される。また、HTTP経由でAPIが呼ばれるため、HTTPのオーバーヘッドも発生する。そのため、
- できる限りプログラムで処理しやすいレスポンスデータ
- APIへのアクセス回数は極力最小限に
を念頭に検討する必要がある。
レスポンスデータのフォーマットを検討する
JSON、XML等のフォーマットを検討する。昔はXML形式が多かったが最近はJSON形式が主流。以下はGoogleトレンドの検索結果(赤は「xml api」、青は「json api」)。
また、主要なWebサービスはJSONを基本としていて、サービスによってはXMLもサポートしている。つまり世のWeb APIはJSONがデファクトスタンダードとなっている模様。なので、深く検討せずJSONで決めてしまい、需要があればXMLもサポートするという形が好ましいと思う。なお、なぜXMLではなくJSONなのかというのは、JSONに押されるXMLの存在にも記載があるが、簡潔にまとめると以下の通り(「XMLが悪い」と否定しているわけではなく、JSONのほうがマッチしているということ)。
- JSONのほうがシンプル
- JSONのほうがJavaScriptとの相性が良い
レスポンスデータを検討する
実際にどんなデータを返すかを検討する。その際の考え方として、冒頭でも記載した通り「APIへのアクセス回数は極力最小限に」ということを念頭に検討する。そのためにもRESTful APIのリソース設計#何をリソースとするかでも記載した通り、APIのユースケースを明確化しておく必要がある。例えば、本の情報を返すAPIがあった場合、以下のようなレスポンスデータ(idのみ)を返すとする。
{
"books": [
00001,
00002,
00003,
00004,
00005
]
}
本のidだけ返却しても、APIを利用する側からするとほとんどの場合あまり意味はない。APIを利用する側のユースケースとしては、「本の情報を一覧表示する」というケースが考えられるので、最低限idの他にも本の名前、本の詳細を記載したページのURL(もちろん詳細のURLではなく出版社、出版日等の詳細情報を直接返却してもよい)も必要としていることが考えられる。そのため、以下のようにすることで一度のAPI呼び出しで必要な情報が全て取得できるので、APIのアクセス回数を少なくさせることができる。
{
"books": [
{
"id": 00001,
"name": "本の名前1",
"url": "http://example.com/books/00001"
},
{
"id": 00002,
"name": "本の名前2",
"url": "http://example.com/books/00002"
},
{
"id": 00003,
"name": "本の名前3",
"url": "http://example.com/books/00003"
}
]
}
各項目の項目名のデータ型の定義
RESTful APIのリソース設計#リソースの各項目のデータ型の定義にも記載した通り、レスポンスデータの各項目のデータ型や項目名を検討する。データモデル設計でやっても問題ないと思うが、どちらかというとリソース設計の段階で検討するべき内容だと思う。なお、項目名を命名する際の注意点としては以下のようなものがある。
- 多くのAPIで同じ意味に利用されている一般的な単語を用いる
- なるべく少ない単語数で表現する
- 変な省略形は極力利用しない
- 複数の単語を連結する場合、その連結方法はAPI全体を通して統一する
- 単数形／複数形に気をつける
エラー発生時のレスポンスデータの検討
RESTful APIのエラー設計で別途まとめた通り。