REST入門基礎知識

はじめに

RESTサービスを開発するにあたって勉強したことをまとめました。RESTとはなんぞやというところについて書いていきます。実際の開発方法等については当記事では触れません。

RESTとは

REST(REpresentational State Transfer)はWebサービスの設計モデルです。RESTなWebサービスは、そのサービスのURIにHTTPメソッドでアクセスすることでデータの送受信を行います。

例としてQiitaのREST APIを利用してみます。下記のURLにアクセスしてみてください。(ChromeかFirefoxでないと*.jsonファイルのダウンロードになる場合があります)

https://qiita.com/api/v2/users/TakahiRoyte

{}でくくられている文字が表示されたかと思います。これは JSON(JavaScript Object Notation) というデータのフォーマットで、整形すると下記のようになります。

{  
  "description":null,
  "facebook_id":null,
  "followees_count":1,
  "followers_count":0,
  "github_login_name":"TakahiRoyte",
  "id":"TakahiRoyte",
  "items_count":3,
  "linkedin_id":null,
  "location":null,
  "name":"",
  "organization":null,
  "permanent_id":89911,
  "profile_image_url":"https://avatars.githubusercontent.com/u/14937252?v=3",
  "twitter_screen_name":"TakahiRoyte",
  "website_url":null
}

これは私(@TakahiRoyte)のユーザー情報です。各行のコロンの左がKey、右がValueになっています。RESTではこのようにデータとして扱いやすいJSON形式が一般的に利用されています。他にはXMLも対応していますがあまり使われていません。

上記の例ではQiitaがAPIとして提供しているリソースを取得(GET)していますが、他にもリソースの登録(POST)、更新(PUT/PATCH)、削除(DELETE)などがRESTにより実現できます。

現在多種多様なWebサービスがRESTのAPIを公開しています。これら公開されているサービス(とそれで得られるデータ)と、自分で作成したシステムを組み合わせて新たなWebサービスを作成できるのがRESTの素晴らしいところです。

RESTの設計原則であるRESTful

RESTは設計に際し以下を設計原則とするよう提言されています。

アドレス指定可能なURIで公開されていること
インターフェース(HTTPメソッドの利用)の統一がされていること
ステートレスであること
処理結果がHTTPステータスコードで通知されること

これらの原則に則ったWebサービスをRESTfulなサービスといいます。
それぞれについてもう少し説明していきます。

アドレス指定可能なURI

アドレス指定可能なURIがどういうものかを先ほどのQiitaのAPIのURIを例に説明します。

https://qiita.com/api/v2/users/TakahiRoyte

上記URIはhttps://qiita.com/api/v2が提供する/users(ユーザー)のなかの筆者(/TakahiRoyte)と指定されています。RESTでは一つのリソースに対してアドレス指定可能なURIが用意されていることが推奨されています。リソースのURIを定義する時にはこのようにディレクトリー構造を模すとシンプルかつ直感的にサービスの利用ができます。

また、URIはあくまでもリソースを示すべきなので名詞のみで構成されることが原則です。/api/getUsersではなく/api/usersとします。これは次に説明するHTTPメソッドとの兼ね合いにおいて大切になります。

インターフェースの統一

RESTで用いられるHTTPメソッドは下記のようにCRUD操作と対応付けられます。

処理	HTTPメソッド	CRUD操作
登録	POST	CREATE
取得	GET	READ
更新	PUT	UPDATE
削除	DELETE	DELETE

RESTではURIで表されたリソースに対して各HTTPメソッドで操作を行います。Google CalendarのAPIの例を見てみましょう。

登録 POST    /calendars/calendarId/events
取得 GET     /calendars/calendarId/events/eventId
更新 PUT     /calendars/calendarId/events/eventId
削除 DELETE  /calendars/calendarId/events/eventId

登録だけ/eventIdが無いのはGoogle Calendarでは/eventIdが自動採番されるためです。/eventIdが振られたイベント(一つのリソース)に対し異なるメソッドで取得、更新、削除などを行います。RESTではこのようにHTTPメソッドを利用するというインターフェースの統一が図られている為、サービスが利用しやすくなっています。

ステートレス

ステートとは「状態」を意味します。よってステートレスは「状態がない」という意味になります。ステートレスなやり取りにおいてサーバーはクライアントのセッション情報を保持しません。逆にステートフルなやり取りにおいてはセッション情報が保持されます。

これだけでは理解しづらいこともあると思うので、下記ブログの客と店員の会話の例を読んでみてください。

yohei-y:weblog ステートレスとは何か

セッション情報はサーバー側で保持されないため、追加注文のたびに前の注文(状態)も合わせて送る必要がでてきます。これは冗長に見えますが、下記のようなメリットがあります。

クライアントのリクエストはリソース操作に必要十分な情報になる
セッション管理がシンプルになる
スケーラブルなシステムにできる

処理結果をHTTPステータスコードで返す

ステータスコードはWebサーバーからのレスポンスを表すコードです。RESTはHTTPメソッドを利用しているのでHTTPステータスコードをその結果として返却するのは自然な流れです。

以下に頻出するHTTPステータスコードをまとめます。

コード	状態	説明
200	OK	リクエストが正常に処理された
201	Created	リクエストが正常に処理され、新規リソースが作成された
204	No Content	リクエストが正常に処理されたが、返す新規情報はない
400	Bad Request	サーバーが理解できない無効な要求である
401	Unauthorized	要求されたリソースには認証が必要である
403	Forbidden	要求されたリクエストは拒否された
404	Not Found	要求されたリソースはサーバーに存在しない
500	Internal Server Error	サーバーでエラーが発生した

まとめ

RESTはあくまでも設計モデルなので、上記を守らずともRESTっぽいWebサービスは作成できます。ですが前述したように、RESTfulなサービスを作ることで異なるサービスでもAPIドキュメントさえ読めば同じように使うことができます。

今は本当に多種多様なREST Webサービスが展開されています。自分の作るアプリケーションにぜひとも組み込んでみて新しい価値を生み出していきたいものですね！

REST入門 基礎知識