//tips
//webapi レスポンスデータ設計
前回まではwebapiへのリクエスト方法を確認したので、今度はリクエストを受けて返されるレスポンスデータの設計についてみていく。
いかにプログラムで処理しやすいレスポンスデータを返せるかがapiの品質に関わってくる。データフォーマットはjsonに対応できていれば問題ない。
Jsonがxmlよりも広まったのは、シンプルで同じデータ量を返す際のサイズが小さくて済むこと、javascriptと相性がいいことなどが挙げられる。
ただ、クライアント側がxmlでデータ取得を行いたいという場合に備えて
v1/users?format=xml
users.json
といったクエリを使用したっルート設計や拡張子ををつけることで対応する。
また、Acceptというリクエストヘッダを使い指定する方法もある。
GET/v1/users
Host:api.example.com
Accept:application/json
さらに、jsonを利用することでJSONPと呼ばれるjsonにjavascriptを付加してjsonのデータを整えて提供してくれるものも利用できる。
APIのレスポンスの際にまず念頭に置くことはアクセス回数がなるべく少なくなるように配慮することがある。
例えば、友人一覧のリクエストを受けた際に、下記のIDデータを返した場合
{
“friends”:[
234342,
93734,
…
]
}
受け取り手は再度このIDをもとに友人一覧画面を表示するために必要な名前や画像などの情報を取得しようとアクセスする必要が出てきてしまう。
これは使い勝手が悪いので、友人一覧リクエストを行った対象が求めているデータを全て一回で渡せるように配慮しなければならない。
{
“friends”:[
{
“id”:234342,
“name”:”Taro Tanaka”,
“profileIcon”:”…png”,
返す内容自体はデータベースの内容だがデータベースの内容をそのまま返すのではなく、データベースの内容を組み合わせて、クライアントの要望を満たす形に変えてあげることがapiに求められている役割である。
ただ、全てのクライアントの求める要望を入れ込みすぎると逆に情報量が膨大になり、クライアントの負担となるので、
users/1234?fields=name,age
などの形でクエリで欲しい情報の絞り込みを行えるようにしておく。
同時にエラーを返すために適切なステータスコード(200や404などのHTTPレスポンスの先頭行につけられるもの)を設定する。
HTTP/1.1 200 OK //ここの部分
ステータスコードには分類があり、１００番は情報、２００番は成功、３００番はリダイレクト、４００番はクライアントサイドエラー、５００番はサーバサイドエラーとされている。
{
“message”:”Not Found”,
“documentation_url”:”https://developer.github.com/v3”
}
