[解決済み] そのREST APIは本当にRPCなのか？ロイ・フィールディングはそう考えているようだ

質問

私がRESTについて知っていると思っていたことの多くは、どうやら間違っているようです - そしてそれは私一人ではありません。この質問には長い前置きがありますが、情報が少し散らばっているので、必要なことだと思われます。あなたがすでにこのトピックに精通しているのであれば、実際の質問は最後になります。

Roy Fieldingの最初の段落から。 REST APIはハイパーテキスト駆動型でなければならない の最初の段落から、彼が自分の仕事が広く誤解されていると考えていることは明らかです。

私は、HTTPベースのインターフェースをREST APIと呼ぶ人の多さにイライラしています。今日の例は SocialSite REST API です。 . これはRPCです。RPCとしか言いようがない。あまりにも多くのカップリングが表示されているので、X評価を与えるべきでしょう。

Fielding氏は、REST APIの属性をいくつか挙げています。そのうちのいくつかは、SOや他のフォーラムでの一般的な慣行と一般的なアドバイスの両方に反しているようです。たとえば

• REST API は、最初の URI (ブックマーク) と、意図する利用者に適した (すなわち、API を使用する可能性のある任意のクライアントによって理解されると期待される) 標準化されたメディアタイプのセット以上の予備知識なしで入力されるべきです。

• REST API は、固定されたリソース名または階層（クライアントとサーバーの明白な結合）を定義してはなりません。

• REST API は、リソースを表現し、アプリケーションの状態を駆動するために使用されるメディアタイプの定義、または既存の標準メディアタイプのための拡張関係名および/またはハイパーテキスト対応のマークアップの定義に、その記述のほぼすべての労力を費やさなければなりません。...

URI 構造や HTTP 動詞の意味よりもはるかに重要な、ハイパーテキスト ("Hypertext") の考え方が中心的な役割を果たします。

私 (Fielding) がハイパーテキストと言うとき、私は、情報がユーザー (またはオートマトン) が選択肢を得、行動を選択するためのアフォーダンスとなるように、情報とコントロールを同時に提示することを意味します。ハイパーメディアは、メディア ストリーム内に時間的なアンカーを含むというテキストの意味を拡張したものに過ぎず、ほとんどの研究者がこの区別を捨てています。

ハイパーテキストは、ブラウザ上のHTMLである必要はありません。機械は、データ形式と関係のタイプを理解すれば、リンクをたどることができます。

この時点では推測ですが、上記の最初の2点は、以下のようなFooリソースのAPIドキュメントが、クライアントとサーバーの間の緊密な結合につながり、RESTfulシステムには適さないことを示唆しているように思います。

GET   /foos/{id}  # read a Foo
POST  /foos/{id}  # create a Foo
PUT   /foos/{id}  # update a Foo

その代わりに、エージェントは、例えば /foos に対して GET リクエストを発行することによって、すべての Foos のための URI を発見することを強制されるべきです。(それらのURIは上記のパターンに従うことが判明するかもしれませんが、それは重要なことではありません)。レスポンスは、各アイテムにどのようにアクセスし、何ができるかを伝えることができるメディアタイプを使用し、上記の3番目のポイントを生じさせる。このため、APIドキュメントは、レスポンスに含まれるハイパーテキストをどのように解釈するかを説明することに重点を置く必要があります。

さらに、FooリソースへのURIが要求されるたびに、応答は、例えば、それらのURIを通じて関連するリソースと親リソースにアクセスしたり、リソースの作成/削除の後にアクションを起こしたりして、エージェントがどのように進めるかを発見するために必要なすべての情報を含んでいます。

システム全体の鍵は、応答がメディアタイプに含まれるハイパーテキストで構成され、それ自体がエージェントに処理を進めるためのオプションを伝えるということです。これは、人間にとってのブラウザの動作に似ています。

しかし、これは現時点での私の最善の推測に過ぎません。

フィールディングが投稿した フォローアップ を投稿し、彼の議論があまりにも抽象的で、例がなく、専門用語が多いという批判に反論しています。

他の人たちは、私が書いたものを、より直接的であったり、今日の実際的な関心事に適用できるような方法で読み解こうとするでしょう。なぜなら、私は次のトピックに取り組んだり、会議の準備をしたり、別の規格を書いたり、遠い場所に旅行したり、給料をもらったと実感できるような小さなことをしたりするのに忙しすぎるからです。

Fieldingが言っていることをどのように解釈し、REST APIを文書化/実装する際にどのようにそれを実践しているのでしょうか？

編集: この質問は、話していることの名前がない場合、何かを学ぶことがどれほど難しいかを示す例です。この場合の名前は "Hypermedia as the Engine of Application State" (HATEOAS)です。