Web APIにおけるデータフォーマットの指定方法

Web API The Good Partsを読んだ。

メモを少し書いておきます。

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

APIのフォーマットはJSONがデファクトスタンダードであるが、XMLもサポートしたい場合などは クライアントにどのように取得したい形式を指定させるべきか考える。

一般的に以下の方法が使われている。

• クエリパラメータを使う方法
• 拡張子を使う方法
• リクエストヘッダでメディアタイプを指定する方法

1つ目のクエリパラメータを使う方法は以下のようにして、jsonやxmlといったデータ形式を指定する方法である。

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

2つ目は拡張子を使う方法で、ファイルに拡張子をつけるのと同じようにURIの最後に.jsonや.xmlをつけてデータ形式を指定するものである。

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

3つ目はAcceptというリクエストヘッダを使う方法である。Acceptは受け取りたいメディアタイプを指定するための HTTPヘッダで、データ形式を指定することで「この形式でデータを受け取りたい」ということをサーバに対して伝えることができる。

どれを使えば良いのか

HTTPの仕様を最大限に活用する場合はリクエストヘッダで指定する場合が理想的であるが、やや敷居が高いという問題がある。 多くのサービスはクエリパラメータで取得することが多い。 本書でもクエリパラメータで取得することを推奨している。