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

参考

RESTful Webサービス
Web API: The Good Parts