【メモ】REST / REST API

## はじめに

REST、REST APIについて以下のUdemy講座で学習したため、重要な点をメモ書きとして残しておくことにします。

https://www.udemy.com/share/103eNc3@0YMUqWiHXE4ujrD_wz1dNUOqMxXjFONoGpyBzaz3BW6KcyqwplnyXXC3dLZfk-ATsQ==/

## REST

- REST（REepresentational State Transfer）
    - 分散型システムにおける設計原則群（設計ルール）のこと
        - アメリカの学者であるRoy Fieldingが2000年に提唱した
- RESTful
    - RESTで求められる原則に従っていること
- REST原則
    - REST原則は、全6種類 ※ nullスタートは除く
        - 1.) クライアント/サーバー
        - 2.) 階層化システム
        - 3.) コードオンデマンド
        - 4.) 統一インターフェース
        - 5.) ステートレス
        - 6.) キャッシュ制御
- REST API
    - RESTをWeb APIに適用したもの
    
## REST原則

### クライアント/サーバー

- 要約
    - よくあるネットワークベースのアプリケーションの構成のこと
- 特徴
    - 画面とデータで関心事を分離する
    - クライアントが動作のトリガーとなり、サーバーは受け身となる

### 階層化システム

- 要約
    - 多層アーキテクチャ構成のこと
- 補足
    - 多層アーキテクチャ構成における個々のサーバーを「コンポーネント」と呼ぶ
- メリット
    - 各コンポーネントに役割を決めてで独立させると、進化と再利用を促進できる
- デメリット
    - データ処理にオーバーヘッドが発生する（ユーザー側から応答が悪く見えてしまう）
        - キャッシュで改善は可能

### コードオンデマンド
- 要約
    - クライアント側でコードをダウンロードし、実行できること
- 補足
    - サーバー側のファイルを更新すると、クライアント側がダウンロードし新環境を構築できる
- メリット
    - リリース済みのクライアントに対して、機能追加ができる
    - クライアントに処理を委譲するため、サーバー負荷を軽減できる
- デメリット
    - 多数のブラウザなど評価環境が複雑になる

### 統一インターフェース

- メリット
    - 疎結合になるため、システムアーキテクチャ全体が簡素化される
    - 接合部分のルール化により提供するサービスに集中でき、独自の進化ができる
    - 異なるブラウザでも同じような画面を表示できる
- デメリット
    - 標準化により効率が犠牲になる

#### 1.) リソースの識別

- リソース
    - 名前を付与できるあらゆるもの（サーバー側に保持されるデータ）
- 要約
    - URIを用いてサーバー側に保持されたデータを識別すること
        - URIに動作は含まない

#### 2.) 表現を用いたリソース操作

- 表現
    - リソース（サーバー側に保持されたデータ）のある断面（4/1の天気、最新の天気）
        - クライアントへ返却されるレスポンス
        - サーバーへPOSTするデータ
- 要約
    - 断面情報を利用してサーバー上のデータを操作すること

#### 3.) 自己記述メッセージ

- 自己記述
    - データ自身がデータの中身を説明している
- メッセージ
    - サーバーへリクエストするデータ
    - クライアントへレスポンスするデータ
- 要約
    - メッセージ内容が何であるかヘッダーに記述されていること

#### 4.) HATEOAS

- HATEOS
    - Hypermedia AS The Engine Of Application State
- 要約
    - レスポンスに現在の状態を踏まえて関連するハイパーリンクを含むこと
- 具体例
    - 検索結果ページにおける次のページ

### ステートレス

- 要約
    - サーバーはリクエストだけでコンテキストを理解できる
- メリット
    - 単一のリクエスト以外を見る必要がないため、監視が容易
    - 障害発生時は単独のリクエストのみ回復すればよいので、障害復旧が容易
    - リクエスト全体でサーバーリソースを共有する必要がないため、スケールが容易
- デメリット
    - 単一のリクエストで完結させるため、リクエストデータに重複がある
    - アプリの複数バージョンを提供している場合
        - 状態をクライアント側に置いてくとアプリ制御が複雑になる 

### キャッシュ制御
- 要約
    - クライアントはレスポンスをキャッシュできる
- メリット
    - ユーザー体験の向上
    - リソース効率の向上
    - 拡張性の向上
- デメリット
    - 古いデータをキャッシュすると、システム対する信頼性の低下を招く

## REST API 設計レベル

Martin Fowlerが2010年にブログで公開したREST API 設計レベルのことを指す。

|LEVEL  | 内容 |
|:-----------|:-----------|
|LEVEL0      | HTTPの利用  |
|LEVEL1      | リソース概念の導入|
|LEVEL2      | HTTP 動詞の導入|
|LEVEL3      | HATEOSの導入|

## HTTPメソッドのURLへの適用

REST APIを設計する上でURIに対して、どうHTTPメソッドを適用すればよいのかまとめる。

### 前提

- URI：リソース
- HTTPメソッド：リソースに対する操作

以下は、「ユーザー情報を取得すること」を指す。

```
GET /v1/users/123 HTTP/1.1
Host: example.com
```

主要なHTTPメソッドと説明は以下の通り。

| メソッド | 説明 |
|:------|:-----------|
|`GET`    | リソースの取得 |
|`POST`   | リソースの新規登録 |
|`PUT`    | 既存リソースの更新 / リソースの新規登録 |
|`DELETE` | リソースの削除 |

### HTTPメソッドとURIの組み合わせ例

URIは同一で、HTTPメソッドを変更することで操作を変更する。

| 操作 | API実装例 |
|:------|:-----------|
| ユーザー情報一覧を取得 | `GET http://api.example.com/users` |
| ユーザーの新規登録 | `POST http://api.example.com/users` |
| 特定ユーザーの取得 | `GET http://api.example.com/users/12345` |
| 特定ユーザーの更新 | `PUT http://api.example.com/users/12345` |
| 特定ユーザーの削除 | `DELETE http://api.example.com/users/12345` |

## CRUD操作のURI、HTTPメソッドの定義

今回学習した内容をもとにアウトプットとして「movieをリソースとしたCRUD操作のURI、HTTPメソッド」を定義してみます。

| URI  | HTTPメソッド |
|:-----------|:-----------|
| `/v1/movies` | `GET`（movie情報一覧を取得） |
| `/v1/movies` | `POST`（movie情報の新規登録） |
| `/v1/movies/:id` | `GET`（特定movieの取得） |
| `/v1/movies/:id` | `PUT`（特定movieの更新） |
| `/v1/movies/:id` | `DELETE`（特定movieの削除） |

## おわりに

かなりインプットの量が多いため、一度学習しただけでは忘れてしまいそうです。復習の際は、再度本メモを利用しようと思います。