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

こんにちは、SESエンジニアのつくねん。です。
前回に引き続きWEB APIのお話です（参考は「Web API The Good Parts」）
今回はレスポンスデータの設計について。
「データフォーマット」と「内部構造」について学んだので残します。

データフォーマット

データフォーマットとは、
WEB APIが返す構造化データをどのように返すかというもので
現在は、JSON形式一択となっているようです。

JSONの他にはXMLなどの形式があるので
JSONに標準で対応しておいて、要望があればXMLに対応が良さそうとのことです。

データフォーマットの指定方法

一般的な指定の方法は以下のようなものがあります。
・クエリパラメータを使う
・フォーマットを指定するクエリパラメータを用意
・リクエストヘッダでメディアタイプを指定

クエリパラメータを使う
フォーマットを指定するクエリパラメータを用意する。

// クエリパラメータでフォーマットを指定（xml）

https://api.example.com/v1/users?format=xml

拡張子を使う
URIの最後に「.」繋ぎでフォーマットをつける。

// 拡張子でフォーマットを指定（json）

https://api.example.com/v1/users.json

リクエストヘッダでメディアタイプを指定
Acceptという受け取りたいメディアタイプを指定するHTTPヘッダで指定する。

// リクエストヘッダでメディアタイプを指定(json)

GET /v1/users
Host: api.example.com
Accept: application/json

どれを使っても良いのですが、
実際に最も使われているのはクエリパラメータとのことです。

データの内部構造

データの内部構造について
まず考えるべきはAPIのアクセス回数をなるべく減らすことで
そのためにはAPIのユースケースを考えることが必要です。
例えばSNSで使うAPIだとして
以下のようにidとnameは一緒に必要だよね？みたいな感じで考えていくそうです。

{
    "friends" : [
        {
            "id":1111,
            "name":"test taro",
            "icon":"XXX/XXX/XXX"
        },
        {
            "id":222,
            "name":"test man",
            "icon":"XXX/XXX/XXX"
        },
        :
    ]
}

レスポンスデータの内容をユーザーが選べるようにする
ただ、あれもこれもと大量データをとってくるのはあまりよろしくないので
レスポンスの内容をユーザーが選べるようにします。
クエリパラメータを使って、例えばユーザー情報のうち名前と年齢が欲しい
みたいにできるようにするといった感じです。

データはフラットにするべきか
構造を階層構造にするのかフラットにするかについては、
なるべくフラットにすべきだけど階層化したほうが絶対に良い場合は階層化が理想とのこと。
GoogleのJSON Style Guideでも「なるべくフラットがいいけど、階層構造を持つ方がわかりやすい場合もあるよね」となっているそうです

配列とフォーマット
APIで配列を返したいケースでは
配列をそのまま返す方法と、
レスポンス全体をオブジェクトにしてその中に配列を入れる方法がある。
どちらでもOKだが、後者を推奨。
理由は
・レスポンスデータが何を示しているかわかりやすくなる
・レスポンスデータをオブジェクトに統一できる
・セキュリティ上のリスクを回避できる
　→JSONインジェクションのリスク。
    →この問題は読み込んだJSONファイルがJSとして正しい文法のために発生

各データの名前
JSONのキーに相当する部分の命名についての注意点は以下の通り。
・一般的な単語を用いる
・なるべく少ない単語数で表現
・単語の連結方法はAPI全体を通して統一
・変な省略形は使わない
・単数/複数に気を付ける

エラーの表現
さまざまな状況でエラーを返すことがありますが、エラーが起きた時に「エラーが発生しました」だけでは不親切です。
そこで、エラーの形式を統一して、クライアント側でエラー詳細を理解可能にすることが必要になります。
具体的には
・ステータスコードを返す
・人間が読めるメッセージを返す
・詳細コードを返す
・詳細情報へのリンク返す
などが考えられます。

エラーの内容を返す方法は
・HTTPのレスポンスヘッダに入れて返す
・レスポンスボディで返す
があり、処理のしやすさからレスポンスボディで返す方法で問題なし。

おわりに

今回はレスポンスデータの設計について学んだことをまとめました。
エラーの詳細に何を返すのかはAPIでまちまちだと思うので
実際に何を返すのか、現場ごとに学んでいきたいですね。