Qiita Teams that are logged in
You are not logged in to any team

Log in to Qiita Team
Community
OrganizationEventAdvent CalendarQiitadon (β)
Service
Qiita JobsQiita ZineQiita Blog
68
Help us understand the problem. What are the problem?

More than 5 years have passed since last update.

posted at

updated at

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

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

Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
68
Help us understand the problem. What are the problem?