Edited at

RESTful APIのレスポンスデータ設計

More than 1 year has passed since last update.

APIを利用する側にレスポンスとしてどのようなデータを返却するかを検討する。


レスポンスデータを設計する上での考え方

APIのレスポンスデータはほとんどの場合プログラムで処理される。また、HTTP経由でAPIが呼ばれるため、HTTPのオーバーヘッドも発生する。そのため、


  • できる限りプログラムで処理しやすいレスポンスデータ

  • APIへのアクセス回数は極力最小限に

を念頭に検討する必要がある。


レスポンスデータのフォーマットを検討する

JSON、XML等のフォーマットを検討する。昔はXML形式が多かったが最近はJSON形式が主流。以下はGoogleトレンドの検索結果(赤は「xml api」、青は「json api」)。

1.png

また、主要な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のエラー設計で別途まとめた通り。


参考

RESTful Webサービス

Web API: The Good Parts