REST APIについて整理する

REST APIについて学んだので整理しておきます。

前提となるWebの知識

REST APIを理解するために必要なWebの知識を整理しておく。

Web

Webとは、HTML文書を閲覧するためのシステム。

HTMLの他にも画像や動画ファイルなども閲覧でき、それらをまとめたコンテンツが置かれているのがWebサーバーで、Webサーバーに対してコンテンツを要求し閲覧するためのソフトウェアがWebブラウザ。

クライアント・サーバー

Webブラウザがクライアントにあたり、Webサーバーがその名の通りサーバーにあたる。Webのシステムはこの2つのソフトウェアがインターネット上でやりとりすることで成り立つ。やりとりは、ブラウザからの要求と、要求に対するサーバーからの返答というシンプルなもの。

HTTP

HTTPはブラウザとサーバーのWebコンテンツのやり取りの際のルールのこと。

HTTPメソッド

HTTPメソッドとは、クライアントからサーバーに対してどんな操作をして欲しいかを指定するもの。

よく使うHTTPメソッドは、GET、POST、PATCH、PUT、DELETE。

代表的なメソッドの操作については以下の表。

HTTPメソッド	操作
GET	リソースの取得
POST	リソースの作成
PATCH	リソースの更新
PUT	リソースの更新
DELETE	リソースの削除

PATCHとPUTの違いは、PATCHは送信されたデータの範囲で部分的に更新し、PUTは既存のデータを完全に更新する、または既存のデータがなければ新しく作成する。

ステータスコード

ステータスコードはサーバーからのレスポンスの結果を3桁の数字で表したもの。

ステータスコード	種類
100番台	リクエストが処理中
200番台	リクエストの成功
300番台	リダイレクト
400番台	クライアントエラー
500番台	サーバーエラー

セッション

セッションはブラウザとサーバーの間で状態を保持しないHTTP通信で、状態を保持したいときに使うもの。

状態を保持しないというのは、ブラウザとサーバーがやり取りするたびに初対面であるようなものでステートレスともいう。

ステートレスな通信はやり取りが簡潔なものであるが、ログイン機能やショッピングサイトのカート機能などのページを更新しても何かしらのデータを保持しておきたいに実現できない。そこでサーバー側でデータを保持しておく技術であるセッションを利用し、ステートレスとは反対のステートフルな通信を可能にする。

キャッシュ

キャッシュとは、一度閲覧したページや画像のデータを保存したもの。キャッシュを使うことで再度閲覧するときに読み込みが早くなる。

REST API

本題のREST APIはRESTとAPIを合わせたものなので、分解してそれぞれが何なのか調べる。

RESTとは

RESTとは、Representational State Transferの略で、webアプリの設計ルールのこと。ここでのwebアプリは主にAPIのこと。

RESTは以下の6つの原則で成り立つ。

クライアント/サーバー
ステートレス
キャッシュ制御
統一インターフェース
階層化システム
コードオンデマンド

これらの原則で成り立ったものをRESTfulという。

クライアント/サーバー

クライアントからの要求に対して、サーバーからのレスポンスを返すWebシステムの構成になっていること。この構成によって画面のクライアントとデータのサーバーで関心ごとを分離できる。

ステートレス

ステートレスであるということはそれぞれの通信は独立しているということ。

キャッシュ制御

クライアントでレスポンスをキャッシュすることで、読み込みを早くできること。

ただしキャッシュによって古い情報が表示されることもある。

統一インターフェース

統一インターフェースとは、リソースをURIで識別し、HTTPメソッドを使うことでURIへの操作方法を統一すること。

具体的な例だと、Userというリソースを扱ってユーザーを作成するという処理を実行したいときに、/createUserではなく、/usersというURIでPOSTメソッドを実行するようにする。 /createUserはURIに動作が含まれているので統一インターフェースではなく、URIは/usersとし、POSTというHTTPメソッドで処理を分けるようにしたのが統一インターフェースになる。ユーザーの作成以外にもユーザーを取得したいときには同じ/usersというURIでGETメソッドを使う。

階層化システム

階層化システムとは、Webを構成する複数のアプリケーションがいくつかの階層になっているものであること。

階層化システムによってそれぞれのアプリを独立させることで、システムの拡大やアプリの再利用などをしやすくする。ただし、複数のアプリを使った構成なのでオーバーヘッドが発生し応答が悪くなるデメリットもある。

コードオンデマンド

コードオンデマンドとは、JavaScriptなどのプログラムコードをサーバーからダウンロードしてクライアント側で実行できること。これによってクライアント側で用意されていない機能を追加できる。

APIとは

APIとは、Application Programming Interfaceの略で、簡単に言えばアプリとアプリをつなぐものである。

APIには多くの種類があり、代表的なものにGoogleマップや、Twitterなどがある。

外部に公開されているAPIを使うことで、さまざまな機能を開発することなく利用できる。

REST APIとは

上記のRESTとAPIの意味から、REST APIとはRESTの原則で設計されたAPIのことになる。

具体的には

クライアント/サーバーの構成になっていて
状態を保持しないステートレスな通信で
キャッシュを使い
リソースをURIで識別しながらHTTPメソッドで操作方法を統一し
階層化されたシステムであり
サーバーからクライアント側で実行するプログラムをダウンロードできる

APIであるということ。

REST APIの設計

REST APIの設計は以下の流れで行う。

どんなデータを利用するか決める
URI設計とHTTPメソッドの指定を行う
レスポンスのデータフォーマットを決める
エラーの設計を行う

1. どんなデータを利用するか決める

まずは利用するリソースを決める。

2. URI設計とHTTPメソッドの指定を行う

リソースからURIを決めて、処理をHTTPメソッドで指定する。

リソースはデータの集合なので、URIに使うリソース名は複数形にするのが基本。

3. レスポンスのデータフォーマットを決める

どんな形式のデータをレスポンスで返すかを決める。主要なデータフォーマットはXML、JSON、JSONPの3種類あり、よく使われるのはJSON。

JSONはJavaScriptを元にしたオブジェクトの形式で、タグを使うXMLに比べ記述が減るのでデータ量を減らすことができる。

{
    animal: {
        name: 'dog'
    }
}

データフォーマットの指定方法はクエリパラメータ、拡張子、リクエストヘッダーの3種類ある。

4. エラーの設計を行う

エラーが起きたかどうかはステータスコードで判断できるが、詳しい情報がわからないので、エラーの詳細をレスポンスボディに入れるようにする。

またAPIのレスポンスではJSONが期待されるので、エラー時にHTMLを返さないようにContent-Typeにapplication/jsonを指定する。

サービス閉塞時には、503エラーとともに、Retry-Afterにいつから再開するのかを示す情報を指定する。

設計の例

映画のデータを扱うAPIをのURIを設計してみる。すると以下のようになる。

URI	HTTP method
/movies	GET
/movies	POST
/movies/:id	PUT
/movies/:id	DELETE

RESTであるAPIとRESTではないAPIの違い

RESTであるAPIは先ほどの映画のAPIのように、movieという1つのリソースにURIが対応する。

movieというリソースがあり、それをHTTPメソッドによって処理を分ける。映画の情報を取得したいならGETメソッドを使い、登録したいならPOSTを使うなど。

RESTではない場合はリソースではなく処理にURIが対応する。例えば、映画の情報を取得したいなら/getMovie、登録したいなら/createMovieというように。

つまりURIにリソースを対応づけるか、処理を対応づけるかが違いであり、 RESTであることで、リソースを示しながら、URIを規則的でシンプルなものにできる。

まとめ

RESTは設計ルールであり、APIはアプリとアプリを接続するインターフェースである。

APIをRESTで設計することで、他の開発者にとってシンプルでわかりやすく、また外部のアプリにとっても連携しやすくなる。