REST APIの始め方 (データ構成)
前回の続きになります。
今回は、返すJSONデータに含まれるもの、データ構成についてみていきます。
また、今回の規定値のフォーマットはJSONタイプとします。
一般的に、RESTサービスについて言及するとき、XMLは考慮しません。 XMLをサポートすることは推奨されていますが、RESTでXMLを使用する人はほとんどいない、ということです。
まず、HTTP Acceptヘッダーの使用は、clientとHTTPサーバーがどのコンテンツタイプをサポートしているかを、HTTP仕様の意図に従って示します。
ただし、サービスからのラップされた応答とアンラップされた応答の両方をサポートするには、Acceptヘッダーを使用するために、独自のカスタム型を実装する必要があります。これにより、クライアントとサービスの複雑さが増します。
その一方で、ファイル拡張形式の書式指定子をサポートすることは簡単で、最小限の文字数で処理を行い、HTTPヘッダーを活用することなく簡単にスクリプトをサポートします。
また、POSTでリソース作成をする際、新しく作成したリソースのURI(リンク)をLocation応答ヘッダーに返す必要があります。レスポンス本体は空にするか、新しく作成したリソースIDのみを入れます。
返されるデータの集合は、それ自身のリンク集合に「自己」リンク特性を最小限に保つべきです。つまりは、自身を表すリンクが、少なくとも含まれます。
該当する場合は、「first」、「previous」、「next」、「last」リンクを使用して、ページネーションを容易にするために、別のリンクコレクションとして返される可能性があります。
Link format(理想的なリンク構成)
リンク形式は標準的に、Atom、AtomPub、またはXlinkに近いスタイルにが推奨されます。 最も普及しているのは、 “rel”要素と “href”要素を持つAtomリンクスタイルを使用したものです。この要素には、認証やクエリ文字列のパラメータがない、リソースの完全なURIが含まれています。 “rel”要素には、標準値 “alternate”、 “related”、 “self”、 “enclosure”、 “via”があります。さらにページングのための “first”、 “last”、 “previous”、 “next”リンクです。これらは意味を成す場所で使用し、必要に応じて追加する必要があります。
XML Atom形式の概念の中には、JSONで表現されるリンクには、関係がないものがあります。たとえば、RESTfulなリソース(URIの中)には、METHODプロパティは不要です。URIは特定のリソースを表し、すべてのHTTPメソッドがサポートされているため、URIにメソッドを入れるのはBad Practiceです。
では、幾つかの例を見て、具体的にどんなresponseが返されるかを確認します。
// 新規のユーザーを、POSTで作成します
POST http://api.example.com/users// here is an set of response headers, with the Lotation header, containing the new resourceURI
// 要は、上で作成が成功した時に、返ってくるヘッダー情報です。 HTTP/1.1 201 CREATED
Status: 201
Connection: close
Content-Type: application/json; charset=utf-8
Location: http://api.example.com/users/12346// また返されるBody、内容はつぎのようになります。JSON形式となっています。それぞれのユーザーを表すURIが、"links"に含まれています。
{“data”:[{“user_id”:”42”, “name”:”Bob”,
“links”:[{“rel”:”self”, “href”:”http://api.example.com/users/42”}]},
{“user_id”:”22”, “name”:”Frank”, “links”: [{“rel”:”self”,
“href”:”http://api.example.com/users/22”}]},
{“user_id”:”125”, “name”: “Sally”, “links”:[{“rel”:”self”,
“href”:”http://api.example.com/users/125”}]}]}// 次に、GETメソッドでリクエストを行った際に返されるJSONデータは、次のようになります。
{“data”:[{“user_id”:”42”, “name”:”Bob”, “links”:[{“rel”:”self”, “href”:”http://api.example.com/users/42”}]},
{“user_id”:”22”, “name”:”Frank”, “links”: [{“rel”:”self”, “href”:”http://api.example.com/users/22”}]},
{“user_id”:”125”, “name”: “Sally”, “links”:[{“rel”:”self”, “href”:”http://api.example.com/users/125”}]}],
“links”:[
{“rel”:“first”, “href”:”http://api.example.com/users?offset=0&limit=3”},
{“rel”:“last”, “href”:”http://api.example.com/users?offset=55&limit=3”},
{“rel”:“previous”, “href”:”http://api.example.com/users?offset=3&limit=3”},
{“rel”:”next”, “href”:”http://api.example.com/users?offset=9&limit=3”}]}
上の例における最後のJSONデータからは、リンクを記述する場所が2つあることが分かります。
それぞれのコレクション(ユーザー情報)ごとの参照リンクと、ページネーション(first, last, previous)など、データ全体の参照先のリンクの2つになります。
返ってくるレスポンスは、HTTPのステータスコードによって行動が決まりますが、clientがそのステータスを成功、失敗、エラーだけを処理するだけいい場合大半です。その為にも、レスポンスそれ自体を、何かにラップする手法が取られます。
主に、ラップされたレスポンスは次の要素をもったものになります。
- code
→
HTTP応答ステータスコード。数値で表されます。 - ステータス
→
「成功」、「失敗」、「エラー」というテキストが含まれます。
「失敗」はHTTPステータスレスポンス値が500〜599の場合、「エラー」はステータス400〜499であり、「成功」はすべてのもの(1XX、2XX、3XXなど)です。 - メッセージ
→
エラーメッセージです。 “失敗” “エラー”ステータスにのみ使用されます。
国際化(i18n)標準で、単独、または区切り文字の中に含まれるメッセージ数や、コードを中に含ませられます。 - data
→
応答本文を含んだもの。 「エラー」または「失敗」ステータスの場合には、原因または例外名が含まれます。
今までの話は、ブラウザが、現在表示しているサイトに対してのみリクエストを行うことを想定したものでした。
では、たとえば、現在表示されているサイトがwww.Example1.comの場合、そのサイトはwww.Example2.comに対してリクエストをどのように実行すれば良いのでしょうか。
こうした、ドメイン間要求をサポートするために広く受け入れられている方法として、JSONPとCross-Origin Resource Sharing(CORS)という2つの方法があります。 ですが、基本的にはCORSが使われます。
CORSの説明は、以下になります。
ウェブブラウザ技術仕様であり、ウェブサーバが異なるドメインのウェブページによってそのリソースにアクセスできるようにする方法を定義しています。これは、JSONPの現代的な代替とみなされ、すべての最新のブラウザでサポートされています。なので、JSONPに代わりに、CORSの使用がお勧めされています。
次は、そのCORSを有効にする方法です。
Access-Control-Allow-Origin:*
「*」のアクセス元は、そのデータが一般消費用である場合にのみ、設定する必要があります。ほとんどの場合、Access-Control-Allow-Originヘッダーでは、CORS要求を行えるドメインを認定する必要があり、クロスドメインにアクセスする必要があるURLにのみ、CORSヘッダーが設定されます。
例:
Access-Control-Allow-Origin:http://example.com:8080 http://foo.example.com
Access-Control-Allow-Origin : ヘッダーに信頼されたドメインのみを許可する。
Access-Control-Allow-Credentials:trueこのヘッダーは、ユーザーがアプリケーションにログインしている場合のクッキー/セッションも送信する為、必要時にのみ使用します。
これらのヘッダーは、Webサーバー、プロキシ経由で構成することも、サービス自体から送信することもできます。
が、基本的にはWebサーバー上の、スペースで区切られた2番目のフォーム(正しいドメインである)を使用します。上の例でいう、 http://foo.example.com です。
詳しいCORSの仕様は、次のリンクで確認できます
以上、APIによってかえされるデータの構成を見ていきました。
次はAPIにおける、クエリの、またページネーションの扱い方について見ていきたいと思います。
