私がRESTについて知っていると思ったことの多くは明らかに間違っています-そして私は一人ではありません。この質問には長いリードインがありますが、情報が少し散らばっているので必要なようです。このトピックに既に精通している場合、実際の質問は最後になります。
RoyFieldingのRESTAPIの最初の段落から、ハイパーテキスト駆動型である必要があります。彼の仕事が広く誤解されていると彼が信じていることは明らかです。
HTTPベースのインターフェースをRESTAPIと呼ぶ人の数に不満を感じています。今日の例はSocialSiteRESTAPIです。それがRPCです。RPCを叫びます。ディスプレイには非常に多くのカップリングがあるため、Xレーティングを付ける必要があります。
フィールディングは、RESTAPIのいくつかの属性をリストします。それらのいくつかは、SOや他のフォーラムでの一般的な慣行と一般的なアドバイスの両方に反しているようです。例えば：
REST APIは、最初のURI（ブックマーク）と対象読者に適した標準化されたメディアタイプのセット（つまり、APIを使用する可能性のあるすべてのクライアントによって理解されることが期待される）以外の事前知識なしで入力する必要があります。..。
REST APIは、固定リソース名または階層（クライアントとサーバーの明らかな結合）を定義してはなりません。..。
REST APIは、リソースの表現やアプリケーションの状態の駆動に使用されるメディアタイプの定義、または既存の標準メディアタイプの拡張リレーション名やハイパーテキスト対応のマークアップの定義に、ほとんどすべての記述的努力を費やす必要があります。..。
「ハイパーテキスト」の概念が中心的な役割を果たします。URI構造やHTTP動詞の意味よりもはるかに重要です。「ハイパーテキスト」は、コメントの1つで定義されています。
私が[フィールディング]ハイパーテキストと言うとき、私は情報とコントロールの同時提示を意味し、情報がユーザー（またはオートマトン）が選択肢を取得してアクションを選択するためのアフォーダンスになるようにします。ハイパーメディアは、メディアストリーム内に一時的なアンカーを含めるためのテキストの意味を拡張したものです。ほとんどの研究者はその区別をやめました。
ブラウザでは、ハイパーテキストは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を介して関連リソースや親リソースにアクセスしたり、作成後にアクションを実行したりする方法を見つけるために必要なすべての情報が含まれます。 /リソースの削除。
システム全体の鍵は、応答がメディアタイプに含まれるハイパーテキストで構成され、それ自体が続行するためのエージェントオプションに伝達されることです。それは、ブラウザが人間のために機能する方法と同じです。
しかし、これはこの特定の瞬間における私の最善の推測です。
フィールディングはフォローアップを投稿し、彼の議論は抽象的すぎ、例が不足しており、専門用語が豊富であるという批判に応えました。
他の人は、私が書いたものを、より直接的であるか、今日のいくつかの実際的な懸念に適用できる方法で解読しようとします。次のトピックに取り組んだり、会議の準備をしたり、別の基準を書いたり、遠くの場所に旅行したり、給料をもらったと感じさせる小さなことをしたりするのに忙しいので、私はおそらくそうしません。
それで、実用的な考え方を持つREST専門家への2つの簡単な質問：フィールディングが言っていることをどのように解釈し、REST APIを文書化/実装するときにそれをどのように実践しますか？
編集：この質問は、あなたが話していることの名前がない場合、何かを学ぶことがどれほど難しいかの一例です。この場合の名前は「アプリケーション状態のエンジンとしてのハイパーメディア」（HATEOAS）です。