REST

どのようなものか

RESTはRepresentational State Transferの略で、Roy
Fieldingが2000年の博士論文の第5章で示したアーキテクチャー様式です。
プロトコルでも標準でもありません。クライアント、サーバー、その間の仲
介者がどうやり取りするかについての制約の集合で、Fieldingは各制約の利
点と、その大半については代償も示しています。形容詞はRESTfulで、厳密
には、すべての制約を守るシステムを指します。日常の用法では、以下の制
約を守るかどうかにかかわらず、JSONをやり取りするほぼすべてのHTTP
APIにまで、両方の言葉の意味が広がっています。

中心となる概念は、リソースです。Fieldingの言葉では、「名前を付けられ
る情報は、何でもリソースになり得ます」。文書、画像、ほかのリソースの
集合、人、ある都市の現在の天気さえ含まれます。ネットワークを流れるの
は、リソース自体では決してなく、その表現です。HTML文書やJPEG画像のよ
うに、バイト列と、そのバイト列を説明するメタデータを組み合わせたもの
です。クライアントは、リソースの現在の状態、あるいは意図する状態の表
現を送受信することで、リソースを操作します。

Fieldingは、制約が何もないところから、一つずつ加えて様式を組み立てま
す。クライアント・サーバーは、ユーザーインターフェースとデータ保存を
分離し、それぞれ独立して発展できるようにします。ステートレスは、各リ
クエストに理解に必要なすべてを含め、サーバーに保存した文脈に依存しな
いことを意味します。そのため、セッションの状態はすべてクライアント側
に置きます。キャッシュは、各レスポンスについて、キャッシュ可能かどう
かを明示的または暗黙的に示すことを求めます。クライアントは、後の同等
のリクエストに、キャッシュ可能なレスポンスを再利用できます。後述する
統一インターフェースは、すべての構成要素に共通の汎用インターフェース
を与えます。階層化システムは、各構成要素が、直接やり取りする層だけを
見ることを意味します。両側のインターフェースを変えずに、プロキシー、
ゲートウェイ、ファイアウォールを間に置けます。コードオンデマンドは、
サーバーが、クライアントで実行するスクリプトを送り、クライアントの機
能を拡張できるようにします。Fieldingは、可視性を下げるため、これだけ
を任意の制約にしています。

彼は、ほかのネットワークベースの様式とRESTを区別する中心的な特徴を、
統一インターフェースと呼び、四つの制約に分けています。リソースを識別
すること（ウェブではURLを使います）、表現を通じてリソースを操作する
こと、メッセージを自己記述的にして、すべての仲介者が意味を理解できる
こと、そして、ハイパーメディアをアプリケーション状態の駆動力とするこ
とです。最後の制約は、人がブラウザーでリンクをたどるように、クライア
ントが受け取った表現から次の遷移を選ぶことを意味します。

なぜ重要なのか

各制約は、特定の利点をもたらします。ステートレスなら、監視システムは
リクエストの外を調べずに理解でき、部分的な障害からの復旧が容易にな
り、サーバーは応答直後にリソースを解放できます。キャッシュは、一部の
やり取りを丸ごと不要にできます。階層化によって、仲介者はネットワーク
やマシンに負荷を分散でき、組織の境界に置いた一つのキャッシュで、内部
の全員に応答できます。また、統一インターフェースは実装と提供するサー
ビスを切り離すため、クライアントとサーバーは、相手も同時に変更しなく
ても、それぞれ変更できます。

Fieldingは代償についても明確です。ステートレスでは、サーバー側で文脈
を共有すれば省けるデータも、リクエストごとに繰り返します。キャッシュ
は古いデータを返すことがあります。層を増やすたびに、処理負担と遅延が
加わります。統一インターフェースは、特定のアプリケーションの必要に合
わせた形ではなく、標準化した形式で情報を運ぶため、効率を下げます。
Fieldingは、ウェブで一般的な、まとまったハイパーメディアデータの転送
向けに設計し、それ以外のやり取りには最適ではないと明言しています。代
替手法が成り立つのは、この点です。GraphQLサーバーは、単一のエンドポ
イントですべてのリクエストを受け、URL以外のものでエンティティーを識
別し、返すフィールドをクライアントが正確に選べるようにします。一方、
gRPCは、サービス定義に宣言したメソッドを呼びます。どちらも、別の種類
の通信に合わせるため、統一インターフェースの一部を手放します。

HTTP
APIでは、統一インターフェースの多くが、すでに用意されています。HTTP
は、意味が合意されたメソッド、ステータスコード、キャッシュや条件付き
リクエスト用のヘッダーフィールドを定義しています。意味を共有している
ため、途中のプロキシーやキャッシュは、そのAPI固有の事情を知らなくて
もメッセージを扱えます。これらを定義どおりに使うAPIは、この仕組みを
追加の実装なしで利用できます。たどるリンクの代わりに、クライアントが
値を埋めるURLテンプレートを渡すAPIは、ハイパーメディアの制約を手放し
ています。クライアントはサーバーのURL構造に依存し、構造が変わると動
作しなくなります。その結び付きをなくすために、統一インターフェースが
あるのです。

実際の活用例

次のやり取りは注文を作成し、新しいリソースのアドレスを`Location`、エ
ンティティータグを`ETag`に入れて応答します。RFC
9110も、201レスポンスの`ETag`を例として挙げています。そのタグを後の
条件付きリクエストの検証子として使えば、二つのクライアントが、気付か
ないまま互いの変更を上書きすることを防げます。

```http
POST /orders HTTP/1.1
Host: api.example.com
Content-Type: application/json

{"item": "notebook", "quantity": 2}

HTTP/1.1 201 Created
Location: /orders/7421
ETag: "v1"
Content-Type: application/json

{"id": 7421, "item": "notebook", "quantity": 2, "status": "open"}
```

どのメソッドにも、すべての仲介者が依拠できる意味があります。RFC
9110はGET、HEAD、OPTIONS、TRACEを安全と定義しています。クライアント
は、サーバーの状態の変更を求めず、期待もしません。PUTとDELETEは、安
全なメソッドとともに冪等であり、同じリクエストを複数回行っても、意図
した効果は一回の場合と同じになります。POSTはどちらでもなく、RFC
5789はPATCHも同じとしています。この二つの性質によって、クローラーは
害を与えずリンクをたどれ、キャッシュは先読みでき、クライアントは応答
前に接続が切れたPUTを繰り返せます。

REST
APIは、汎用HTTPクライアントだけで操作できます。このサイトには、それ
で何が省け、何が代償になるかの両方の例があります。コードから二台目の
サーバーを構築した際、ベンダーのコレクションではなく、汎用HTTPタスク
で、両クラウド事業者のファイアウォールをREST
APIから直接設定しました。依存関係とそのバージョンのずれをなくす代わ
りに、すべてのリクエストの形を手で書く必要があります。同じ実績は、二
つ目の代償も挙げています。汎用HTTPタスクはチェックモードへの対応を宣
言していないため、マシンを作るプレイをドライランすると、その中のすべ
てのタスクがスキップされます。

問題が起きるところ

GETが何かを変更する。
取得するだけで注文を取り消す`/orders/7421/cancel`のようなアドレス
は、GETは安全であるという約束に反します。RFC
9110は、クローラーや先読みするキャッシュが、害を与える心配なく動ける
ように、この約束があると説明しています。最初にそのリンクを見つけたク
ローラーや先読みキャッシュが、注文を取り消してしまいます。代わりに、
注文に対するPOSTや、状態に対するPATCHとして、動作をメソッドに持たせ
ます。

すべての応答が200 OKになる。
どんな場合も200を返し、エラーかどうかも含め、実際の結果を本文に入れ
るAPIがあります。メッセージは自己記述的でなくなります。キャッシュ、
プロキシー、監視、クライアントライブラリーは、すべてステータスコード
を読み、成功と判断します。RFC
9457は、エラー用の標準本文として、`application/problem+json`を定め、
`type`、`title`、`status`、`detail`などのメンバーを用意しています。
`status`メンバーは助言にすぎません。この形式を知らない汎用HTTPソフト
ウェアが正しく動くように、サーバーは、HTTPレスポンス自体でも同じス
テータスコードを送らなければなりません。

POSTの再試行で、注文が二つ作られる。
サーバーがPOSTを処理した後、クライアントが応答を読む前に接続が切れる
と、クライアントには注文が存在するか分かりません。RFC
9110は、実はそのリクエストが冪等だと分かっているか、最初の試行が適用
されていないと判断できるのでなければ、非冪等なリクエストを自動再試行
すべきではなく、プロキシーはその自動再試行をしてはならないと定めてい
ます。また、特にアイドル状態の持続的接続で、応答をまったく受信する前
に接続が閉じた場合、あえてPOSTを再試行する、より危険な動作を取るクラ
イアントもあると説明しています。対策の一つは、クライアントが識別子を
選び、その場所へ注文をPUTすることです。PUTは冪等なので、最初のリクエ
ストが注文を作って201を返し、繰り返しは同じ状態で置き換えるだけにな
ります。

二つのクライアントが、互いの変更を上書きする。
両方が注文を読み、それぞれ別のフィールドを変え、全体をPUTで戻すと、
二回目の書き込みが、気付かれないまま最初の変更を取り消します。RFC
9110は、これを更新の喪失と呼びます。対策は、注文を読んだときに各クラ
イアントが受け取ったエンティティータグを、`If-Match`で送り返すことで
す。サーバーは、そのクライアントが最後に見た状態のままである場合にだ
け、変更を適用します。違う場合は適用してはならず、412
Precondition Failedで知らせることができます。クライアントは、注文を
読み直し、自分の変更を再び加え、もう一度試します。

```http
PUT /orders/7421 HTTP/1.1
Host: api.example.com
If-Match: "v1"
Content-Type: application/json

{"item": "notebook", "quantity": 3, "status": "open"}

HTTP/1.1 412 Precondition Failed
```

サーバーが会話を記憶する。
一覧の現在のページや、メモリーに置いた入力途中のフォームなど、リクエ
スト間でクライアントごとの状態を保持するサーバーは、ステートレスの制
約を捨てています。リクエストだけでは意味が分からなくなり、ロードバラ
ンサーは各クライアントを同じマシンに戻す必要があり、再起動でその状態
を失います。Fieldingが挙げたステートレスの利点、すなわち可視性、部分
的な障害からの復旧の容易さ、応答後にサーバーがリソースを解放できるこ
とが、そのまま失われます。状態は、URL内のページトークンのようにリク
エストに含めるか、入力途中のものを下書きの注文など独立したリソースに
して、どのサーバーからも読めるようにします。

参考資料

  * Fielding、第5章：Representational State Transfer（REST） —
定義そのものです。各制約、それによって得られる性質、その代償を説明し
ます。

  * RFC 9110：HTTP Semantics —
メソッド、安全性と冪等性、ステータスコード、`ETag`と`If-Match`による
条件付きリクエストを説明します。

  * RFC 5789：PATCH Method for HTTP —
リソースの部分的な変更と、PATCHが安全でも冪等でもない理由です。

  * RFC 9457：Problem Details for HTTP APIs —
ステータスコードの意味を保つ、エラーレスポンス用の標準JSON本文です。

hこのページのウェブ版	URL:https://engineer.company/ja/glossary/rest/	engineer.company	70
