REST API とはなにか？
REST API とは一言でいうと REST に則って設計された Web API のことです。つまり Web API と REST が何を意味するかがわかれば、REST API の大枠をつかむことができると言えるはずです。
それでは「Web API」と「REST」がなにかを解説していきます。
① Web API とは？
まず前提として API（Application Programming Interface） とは、機能やデータを外部から呼び出して利用する規約のことです。API という言葉の定義自体が広く、種類も沢山あるので一括りにしてまとめるのが難しい概念でもあります。
代表的な API としては、以下が挙げられます。
ライブラリ APIOS が提供する APIブラウザ API- JavaScript の上に乗っかって、より簡単に機能を実装するためにブラウザに組み込まれた API
Web API
このように API の種類は多岐にわたっており、中でも Web API は HTTP 通信などの Web 技術を使用することが特徴として挙げられます。この一部に REST API が含まれるのです。
② REST とは？
REST（REpresentational State Transfer）とは、日本語で「分散型システムにおける設計原則群」です。
REST API を設計する上では、以下 6 つで構成されるREST 制約をおさえる必要があります。
REST 制約
クライアント/サーバー- 画面(UI)はクライアント側、データはサーバー側とすることで関心事を分離する。
- クライアント側がトリガーとして、サーバーは受け身の体制を取る。
階層化システムコードオンデマンド- クライアントコードをダウンロードして、実行できる。
統一インターフェースステートレス- サーバーに保存したセッション情報を使わず、状態情報はすべてリクエストに含まれる。
キャッシュ制御- クライアント側でレスポンスをキャッシュできる。
REST API の成熟度モデル
また、REST API 設計には、どれだけ REST 制約に準拠しているかに応じたレベルがあります。 以下の 4 段階の設計レベルです。
LEVEL0：HTTP を使用しているLEVEL1：リソースの概念を導入している（リソースごとに URL 分割）LEVEL2：HTTP メソッドを使用しているLEVEL3：レスポンスに リソース間のつながりが含まれる
③ REST Web API サービス設計
次に REST WebAPI を作成する際にどのようなポイントに気をつける必要があるかを説明します。
③-1：URI の設計
- 短く入力しやすい URI にする（冗長なパスを含まない）
- 人間が理解できる単語を使用する
- すべて小文字で表現する
- 単語はハイフンで結合する
- 単語は複数形を使用する
- エンコードを必要とする文字を使用しない
- サーバー側のアーキテクチャを反映しない
- 改造しやすい
- ルールが統一されている（パスパラメータ or クエリパラメータなど）
③-2：URI と HTTP メソッドの適切な組み合わせ
URI がリソースを示すのに対し、HTTP メソッドはリソースに対する操作を示します。 共通の URI に対して、HTTP メソッドを切り替えることで分かりやすい API になります。
| 操作 | HTTP method | API 実装例 |
|---|---|---|
| ユーザ一覧の取得 | GET | http://sample.com/users |
| ユーザの新規登録 | POST | http://sample.com/users |
| 特定ユーザの取得 | GET | http://sample.com/users/123 |
| ユーザの更新 | PUT | http://sample.com/users/123 |
| ユーザの削除 | DELETE | http://sample.com/users/123 |
③-3：リソースを特定するパラメータの使い分け
リソースを絞り込む方法には、クエリパラメータとパスパラメータの 2 種類があります。 使い分ける基準は以下の通りです。
クエリパラメータ：使わないパラメータが省略可能な場合に使用する（検索条件の絞り込みなど）パスパラメータ：一意なリソースを表現できる場合に使用する
③-4：ステータスコードの使い分け
ステータスコードは大きく 5 つに分類されます。
| ステータスコード | 役割 |
|---|---|
| 100 番台 | 情報にまつわる |
| 200 番台 | 成功レスポンス |
| 300 番台 | リダイレクトメッセージ |
| 400 番台 | クライアントエラーレスポンス |
| 500 番台 | サーバーエラーレスポンス |
※300 番台はリダイレクト処理に関するため REST API ではあまり利用することはない。
(参考サイト) https://developer.mozilla.org/ja/docs/Web/HTTP/Status
③-5：レスポンスのデータフォーマットと指定方法
REST API で扱うデータフォーマットは以下の3種類です。
仮に JSON で指定する場合、指定方法は下記のようになります。 中でも URI がリソースであることを踏まえると、リクエストヘッダで指定するのが適切です。
| フォーマット | 例 |
|---|---|
| クエリパラメータ | http://sample.com/users?format=json |
| 拡張子 | http://sample.com/users.json |
| リクエストヘッダー | GET http://sample.com/users?format=json Host: sample.com Accept: application/json |
④ 実際に REST API を設計してみる
最後にmovie をリソースとして CRUD 操作の URI、HTTP メソッドを定義してみます。
共通の URI を使用することで、REST API の設計が簡単になってますね。
| URI | HTTP method | 操作 |
|---|---|---|
| /movies | GET | 映画の一覧取得 |
| /movies | POST | 映画の新規登録 |
| /movies/:id | GET | 特定の映画取得 |
| /movies/:id | PUT | 特定の映画更新 |
| /movies/:id | DELETE | 特定の映画削除 |
