- ブラウザURL入力今ここ
- DNS名前→IP
- ルータ経路選択
- ロードバランサ振り分け
- Nginx受け口
- アプリ処理今ここ
- DB保存
API の設計語彙を原典に当たって確かめる回です。地図の上では、ブラウザとアプリの間で取り交わされるものにあたります。
まず結論
Fielding の博士論文は REST を4つのインタフェース制約で定義しており、その4つ目が hypermedia as the engine of application state です。URL の付け方は入っていません。
彼が2008年に自分のブログで問題にしたのは「行き先を知っていること」ではなく、その知識が API 固有の URL 構造という形で持たれることでした。
「REST の4つのインタフェース制約」を Fielding の博士論文から挙げるとき、4つ目に来るものは何でしょうか。
当てることが目的ではありません。外した予測ほど記憶に残るので、直感で選んでください。
論文が「REST の定義」として挙げている4つ
REST という語の出所は、Roy T. Fielding が2000年に提出した博士論文です。第5章 §5.1.5 に定義があります。
In order to obtain a uniform interface, multiple architectural constraints are needed to guide the behavior of components. REST is defined by four interface constraints: identification of resources; manipulation of resources through representations; self-descriptive messages; and, hypermedia as the engine of application state.
この4つ目が、状態遷移がハイパーメディアで駆動されることです。
確認したいのは何が書かれていないかのほうです。パスを名詞にすることも、複数形にすることも、メソッドの使い分けも、本文を JSON にすることも、この4つには出てきません。識別することは要求されますが、どう綴るかは論文の関心事ではありません。
- ・URL やメソッドの整備は別の理由で価値があるが、4つ目の代わりではない
Fielding 自身が2008年に書いたこと
論文から8年後、Fielding は自分のブログに記事を1本書きました。査読論文でも規格でもなく、本人名義のブログ記事です。冒頭はこうです。
I am getting frustrated by the number of people calling any HTTP-based interface a REST API. Today’s example is the SocialSite REST API. That is RPC. It screams RPC. There is so much coupling on display that it should be given an X rating.
中身は API 設計者に向けた6項目の箇条書きで、4項目目が本回の芯です。
A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). Servers must have the freedom to control their own namespace.
固定のリソース名や階層の定義を、彼はクライアントとサーバの明白な結合と呼びます。サーバが自分の名前空間を制御する自由を失うからです。6項目目はこうです。
A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience …
「Fielding は REST API の大半が定義を満たしていないと書いている」という説明の評価はどれですか。
争点は「知っているかどうか」ではなく「どこに置かれているか」
「クライアントは最初から行き先を知っているので、リンクを辿る必要がない」——もっともらしい説明ですが、Fielding はこれを明示的に否定しています。 同じ記事のコメント欄でこう書いています。
Of course the client has prior knowledge. Every protocol, every media type definition, every URI scheme, and every link relationship type constitutes prior knowledge that the client must know (or learn) in order to make use of that knowledge. REST doesn’t eliminate the need for a clue. What REST does is concentrate that need for prior knowledge into readily standardizable forms.
事前知識があること自体は当然の前提で、REST が変えようとしているのは知識の量ではなく置き場所です。
- 標準化された媒体型やリンク関係の形で持つ — 多数の相手に使い回せます
- その API 固有の URL 構造の形で持つ — 4項目目の
an obvious coupling of client and serverが生じます
「リンクを辿るクライアントを書くのが面倒だから普及しない」という説明は、原典の順序を取り違えています。問題にされているのは面倒さではなく、知識の置き場所が結合になることです。
対比例 — ブラウザという、例外のほう
4つ目の制約が大規模に動いている例が目の前にあります。ブラウザです。
ブラウザが持つ事前知識は、HTTP と HTML と URI の綴り方、そしてリンクの意味です。個別のサイトの URL 構造は持っていません。 起点はブックマーク1個で、そこから先は返ってきた表現に書いてあります。Fielding もコメント欄でブラウザを例に挙げています。
Think of it in terms of the Web. How many Web browsers are aware of the distinction between an online-banking resource and a Wiki resource? None of them. They don’t need to be aware of the resource types.
銀行のサイトと Wiki の区別を認識しているブラウザはひとつも無い、という指摘です。必要なのは遷移の可能性、つまりリンクとフォームだ、と続きます。
クライアント 知っていること 知らないことブラウザ HTTP / HTML / リンクの意味 個別サイトの URL 構造API 向け HTTP / その API の URL 構造 他の API の使い方
ブラウザが例外なのは、汎用クライアントだからです。 特定の相手のために書かれていないので、標準化された形の知識しか持ちようがありません。逆に、ひとつの API のために書かれたクライアントには、URL 構造を抱え込む道が開いています。抱え込んだぶんだけ、サーバは名前空間を動かせません。
「REST はクライアントから事前知識を無くすための制約である」という説明を、Fielding の記述に照らすとどうなりますか。
リンクを辿るブラウザと、URL を組み立てるクライアント
ブラウザは HTML とリンクの意味だけを知り、遷移先は返ってきた表現から取ります。API 向けのクライアントは、その API の URL 構造をコードに持ち、遷移先を自分で組み立てます。サーバが名前空間を変えたとき、後者だけ書き換えが要ります。
知識の置き場所 変更の影響 流用できる範囲標準化された媒体型 受けない その媒体型の全相手API 固有の URL 構造 書き換えが要る その API だけ
索引の列の並びへの依存(DB編)
複合索引は列の並びという内部構造を持ち、問い合わせがその並びに合っていれば効きます。書く側は索引の有無ではなく列の並びに依存しています。DB編『索引が使われない理由 — 左端プレフィックスと、その反例』の話です。
依存先 構造が変わると 流用できる範囲表の列と条件の意味 効き方が変わる 同じ表の全問い合わせ索引の列の並び 効かなくなる その索引が在るときだけ
クライアントが URL を組み立てることと、問い合わせが索引の列の並びを当てにすること。共通する構造は何でしょうか。
どちらも「知っていること」自体は避けられません。相手が内部を変えたとき壊れるかどうかが何で分かれるかを考えてみてください。
この章のまとめ
- 博士論文 §5.1.5 は REST を4つのインタフェース制約で定義し、4つ目に
hypermedia as the engine of application stateを置く。URL の綴り方・メソッド・JSON はその4つに無い。 - 2008年のブログ記事(論文ではない)で、彼は固定のリソース名や階層の定義を
an obvious coupling of client and serverと呼んだ。 - 争点は事前知識の有無ではなく置き場所。
Of course the client has prior knowledge.とコメント欄で明言している。 - ブラウザは4つ目が動いている例だが、汎用クライアントだからこそ成り立つ。
- 「大半の API が定義を満たさない」は本教材の見方。Fielding は量を書いていない。
自分の現場で確かめる
読んだだけでは身につきません。手元の環境で実際に見てみてください。
理解度チェック
読んだ直後は「分かった」と感じやすいものです。実際に解いて確かめてください。
2008年のブログで Fielding が「クライアントとサーバの明白な結合」と呼んだのは、何をしたときですか。
用語集(4語)
- 統一インタフェース (uniform interface)
- 博士論文 §5.1.5 の制約。これを得るのに4つの下位制約が要るとされ、その4つが REST の定義になっている。4つ目が hypermedia as the engine of application state。
- hypermedia as the engine of application state
- 4つ目のインタフェース制約。状態遷移を、返ってきた表現に提示された選択肢から選ぶ形で駆動するという要求。HATEOAS の略称で呼ばれる。
- out-of-band information
- 2008年のブログの語。やり取りされる表現の外側でクライアントが持つ前提のこと。資源の構造をこの形で仮定することを、ブログは RPC の関数結合に相当するとしている。
- 汎用クライアント (この教材での言い方)
- 特定の API 向けではなく、標準化された媒体型を理解することで多数の相手を扱えるクライアント。ブラウザが代表例。