メニュー

REST とは

エンジニアブログ

記事投稿 | 2017.07.25

こんにちは。sakura@818uuuです。
初めてエンジニアブログを書くので至らない点が多数あるかと思いますが、よろしくお願いします。
今回は REST の基礎的なことについて書きます。

0. はじめに

この記事では REST に関する基礎的な情報を書いています。
前提知識として HTTPの仕組み と Web API が大まかにどんなものかをわかっている方を対象に書いています。

1. RESTとは

RESTとは HTTP をベースとしたアーキテクチャスタイルのことです。
参考文献[1] Wikipedia [ https://en.wikipedia.org/wiki/Representational_state_transfer ]では REST を次のように表現しています。

Representational state transfer (REST) or RESTful web services is a way of providing interoperability between computer systems on the Internet.

REST は Web API の一種であり REST API とも呼ばれます。
( この記事では REST のことを REST API と表記します。また、Web API とは何かを知りたい場合は参考文献[2] Web API: The Good Parts. の1章を参照するとよいと思います。 )
Web API には様々な種類があり、 REST API の他に SOAP API や XML-RPC などがあります。そのなかでも現在( 2017年7月時点 )は REST が主流だといわれています。以下の画像は参考文献[3] Google Trends で Web API の3種類を比較してみた結果です。

REST API が主流であるということは参考文献[4] ProgrammableWeb [ https://www.programmableweb.com/ ]でそれぞれの Web API の Architectural Style を見ると、ほぼ REST を採用していることからも推測することができます。( なにかわかりやすい最新の Web API のデータをまとめたものがあればよりよかったのですが、 少し古いデータしか見つかりませんでした…。申し訳ありません。 )

代表的な Web API の Architectural Style をいくつか紹介しておきます。

Web API名 Architectural Style
Google Maps API REST API
Twitter API REST API
YouTube API REST API
Flickr API REST API
Facebook API REST API
Wikipedia API REST API
Bing API REST API
Instagram API REST API

上記の表で調べた Web API は全て REST API を採用していました。

REST API は設計し提供する側とそれを使用する側の2つの面があります。

まず、REST API を設計し提供する側について、提供するまでの大まかな手順を以下に書きます。

  1. まずどのような機能を REST API として提供すべきかを決めます。
  2. その機能がどのようなリソース(もの)とどのような操作で実現できるかを考えます。
    REST API ではリクエストでどのようなリソースかを URI で、リソースに対してどのような操作をしたいかを HTTP のメソッドで表現します。
  3. リクエストに関する設計をした後、レスポンスに関する設計を行います。
    レスポンスに関する設計ではどのようにデータを返すかやどんなステータスコードを使用するかを決めます。
  4. 全体の設計が終わり次第、REST API を提供します。また、REST API の使い方を示すためにドキュメントの作成などを行います。

次に REST API を使用する側の大まかな方法を以下に書きます。
今回は具体例として Twitter を例にします。
Twitter の REST API には” Twitter でユーザーのフォローしている人の ID 一覧の情報を提供する機能 “があります。
どのように使用するかというと、REST API のルールに則った URI と HTTP のメソッドを使用してリクエストを送ります。 具体的には以下のようにリクエストを送ると、レスポンスとしてフォローしている人の ID 一覧の情報を手に入れることができます。
GET https://api.twitter.com/1.1/friends/ids.json
( 参考文献[5] GET friends/ids – フォローしているユーザーをIDの一覧で取得する [ https://syncer.jp/Web/API/Twitter/REST_API/GET/friends/ids/ ] をご覧いただけるとわかりやすいと思います。)

大まかにですが REST API のことが想像ついたでしょうか。
この記事では REST API の URI や メソッド、レスポンスのステータスコードなどに関して少しだけ説明しようと思います。

2. リクエスト

REST API ではリクエストでどのようなリソースかを URI で、リソースに対してどのような操作をしたいかを HTTP のメソッドで表現します。
以下で URI と メソッドを少しだけ説明します。

2.1 URI

REST API はどのようなリソースかを URI で 、リソースに対してどのような操作をしたいかを HTTP のリクエストのメソッドで表現します。

REST API の URI 設計はどのようなリソースかが一目でわかるような URI 設計を行います。
まず、実際に使用されている Pinterest ( 画像共有 SNS サービス ) の URI を見てみましょう。
( 参考文献[6] Pinterest Developers [ https://developers.pinterest.com/docs/api/users/ ] )

ex: https://api.pinterest.com/v1/me/boards/
この URI をみただけでおそらく Pinterest の REST API のバージョンは1で、自分自身の投稿がされているボードを示しているだろうとわかります。

ex: https://api.pinterest.com/v1/me/followers/
こちらも URI をみただけで Pinterest の REST API のバージョンは1で、自分自身のフォロワーの情報を示しているだろうとわかります。

このように優れた URI 設計がされている URI は一目見ただけでどのようなリソースかわかるようになっています。
URI 設計を行う際に、利用する英単語に気をつかったり、検索のクエリパラメータをどのように書くかなど気をつける点や工夫する点がたくさんあります。
細かな URI 設計の話は今回は省略させていただきますが、詳しく知りたい場合は 参考文献[2]Web API: The Good Parts または 主要な REST API のドキュメントを参考とよいと思います。

2.2 リクエストのメソッド

REST API はどのようなリソースかを URI で、 リソースに対してどのような操作をしたいかを HTTP のリクエストのメソッドで表現します。
HTTP のメソッドは URI の設計と違い、HTTP の RFC で定められているメソッドを使用します。

代表的なもメソッドをいくつか紹介しておきます。

メソッド名 説明
GET リソースの取得( ヘッダ情報 + エンティティボディ情報 を取得)
HEAD リソースの取得( ヘッダ情報のみ取得 )
POST リソースの登録( Create )
PUT リソースの更新( Replace )
DELETE リソースの削除

HTTP のメソッドに関して詳しく知りたい場合は参考文献[7] RFC2616 日本語訳 [ http://www.spencernetwork.org/reference/rfc2616-ja-HTTP1.1.txt ]のセクション9をご覧ください。

3.レスポンス

REST API はどのようなリソースかを URI で、リソースに対してどのような操作をしたいかを HTTP のリクエストのメソッドで表現します。
そして HTTP のレスポンスでリクエストの結果を返します。
REST API ではレスポンスデータをどのように設計するかも考える必要があります。

ここではレスポンスのなかで、ステータスコードとエンティティボディのフォーマットに関して少しだけ説明しようと思います。

3.1 ステータスコード

REST API ではリクエストされた情報をレスポンスとしてステータスコードとともに返します。
ステータスコードとはレスポンスの状態を表す3桁の数字 です。
レスポンスを設計するときに適切なステータスコードを選択することが重要です。なぜ重要かというと、エラーが発生したときに適切なステータスコードで返ってくるとどのようなエラーかを把握しやすいというのが1つの理由です。

代表的なステータスコードをいくつか紹介しておきます。

ステータスコード 説明句 意味
200 OK リクエスト成功
201 Created リクエストを受け入れ新しいリソースを作成した
204 No Content リクエストを受け入れたがエンティティボディは返さない
301 Moved Permanently 恒久的な移動
303 See Other 新規リソースへの移動
307 Temporary Redirect 一時的なリダイレクト
400 Bad Request リクエストが間違っています
403 Forbidden アクセス権限がありません
404 Not Found 指定したリソースがみつかりません
409 Conflict リクエストされたリソースと
サーバーにあるリソースが競合しています
500 Internal Server Error サーバー側でエラーが発生しました
503 Service Unavailable 一時的にサーバーにアクセスできません

詳しく知りたい場合は、参考文献[7] RFC2616 日本語訳
[ http://www.spencernetwork.org/reference/rfc2616-ja-HTTP1.1.txt ] のセクション6.1, セクション10をご覧ください。

3.2 エンティティボディのフォーマット

REST API ではリクエストされた情報をレスポンスとして返します。
レスポンスを返す上で、なるべく小さいデータ量で返すことやプログラムで処理をしやすいフォーマットで返してあげることが大切です。
REST API で HTTP のレスポンスのエンティティボディのフォーマットは JSON をサポートすることが主流だといわれています。
それぞれの Web API がレスポンスのエンティティボディに対してどのようなフォーマットをサポートしているのかを調べるには、参考文献[4] ProgrammableWeb [ https://www.programmableweb.com/ ] で それぞれの Web API の Supported Response Formats を調べるとわかります。

代表的な REST API の Supported Response Formats をいくつか紹介しておきます。

REST API名 Supported Response Formats
Google Maps API XML, JSON, KML
Twitter API JSON, XML, RSS, Atom
YouTube API XML, JSON, GData, Atom, RSS
Flickr API XML, SOAP, JSON, JSONP
Facebook API JSON
Wikipedia API JSON, XML, YAML
Bing API XML, SOAP, JSON
Instagram API JSON, JSONP

どの REST API も JSON をサポートしていることがわかります。

4. その他

その他に REST API に関して参考にした資料や様々な Web API を知る方法などを紹介しておきます。

4.1 RESTful とは

REST API に関して調べると時折 RESTful という言葉を目にします。
RESTful とは REST に従って設計されているアーキテクチャのことです。
なぜ RESTful という言葉が生まれたのか、少し古い( 2009年 )ですが参考文献[8] 「RESTful」と「なんちゃってREST」 – Convivial-Web[ http://convivial-web.net/?p=126 ]に考察が記載されています。

4.2 REST API に関する資料

上記で紹介した以外に REST API に関してわかりやすい資料がいくつかあったので紹介しておきます。

参考文献[9] REST API のコツ
[ https://www.slideshare.net/pospome/rest-api-57207424 ]
REST API の基礎を踏まえた上での資料です。実際に REST API を実装する際に役立つと思います。

参考文献[10] RESTful Web アプリの設計レビューの話
[ https://www.slideshare.net/t_wada/restful-web-design-review ]
少し古い資料( 2012年 )ですが、全体的にまとまっておりとても参考になる資料だと思います。

4.3 Web API を一覧できるサイト

参考文献[4] ProgrammableWeb [ https://www.programmableweb.com/ ] というサイトでは現在( 2017年7月時点 )、約1万7千種類以上の Web API の情報を調べることができます。
REST API を設計する際には既存の Web API 参考にすることがあると思いますので、そのようなときに活用できると思います。

5. まとめ

REST API について少しでも知っていただくことはできたしょうか。
この記事では詳細な URI 設計など REST API の深いところまで触れることはできませんでしたので、参考資料をご覧いただけると幸いです。
拙い文章でしたが読んでいただきありがとうございました。

6. 参考資料

[1] Representational state transfer – Wikipedia, Wikipedia, 2017年7月20日更新( 最終閲覧日:2017年7月21日 )
[ https://en.wikipedia.org/wiki/Representational_state_transfer ]
[2] 水野 貴明. 『Web API: The Good Parts』. オライリージャパン, 2014, 224p.
[3] REST API, SOAP API, XML-RPC – 調べる – Google トレンド , Google Trend, 2017年7月21日更新( 最終閲覧日:2017年7月21日 )
https://trends.google.co.jp/trends/explore?date=today%205-y&q=REST%20API,SOAP%20API,XML-RPC
[4] ProgrammableWeb – APIs, Mashups and the Web as Platform, ProgrammableWeb, 2017年7月21日更新( 最終閲覧日:2017年7月21日 )
[ https://www.programmableweb.com/ ]
[5] GET friends/ids – フォローしているユーザーをIDの一覧で取得する, SYNCER, 2017年7月21日更新( 最終閲覧日:2017年7月21日 )
[ https://syncer.jp/Web/API/Twitter/REST_API/GET/friends/ids/ ]
[6] Pinterest Developers, Pinterest Developers, 最終更新日時不明( 最終閲覧日:2017年7月21日 )
[ https://developers.pinterest.com/docs/api/users/ ]
[7] REC2616 日本語訳, 2004年5月18日更新( 最終閲覧日:2017年7月21日 )
[ http://www.spencernetwork.org/reference/rfc2616-ja-HTTP1.1.txt ]
[8] Hirotoshi Maeda, 「RESTful」と「なんちゃってREST」 – Convivial-Web, CONVIVIAL-WEB, 2009年3月14日更新( 最終閲覧日:2017年7月21日 )
[ http://convivial-web.net/?p=126 ]
[9] pospome, REST API のコツ, SlideShare , 2016年1月19日更新( 最終閲覧日:2017年7月21日 )
[ https://www.slideshare.net/pospome/rest-api-57207424 ]
[10] Takuto Wada, RESTful Web アプリの設計レビューの話, SlideShare , 2012年7月23日更新( 最終閲覧日:2017年7月21日 )
[ https://www.slideshare.net/t_wada/restful-web-design-review ]

PAGE TOP