REST APIは本当にRPCですか？）ロイフィールディングはそう考えるようです
RESTは明らかに間違っていると私が思ったものの多くは間違いです-そして私は一人ではありません。この質問は長い引き合いがありますが、情報がこのトピックにすでに精通している場合、実際の質問は最後に来ます。
Roy Fieldingの最初の段落 REST APIはハイパーテキスト駆動である必要があります から、彼の仕事が広く誤解されていると彼が信じていることは明らかです。
HTTPベースのインターフェースa REST APIを呼び出す人の数に不満を感じています。今日の例は SocialSite REST API です。 =。これはRPCです。RPCを叫びます。ディスプレイには非常に多くのカップリングがあり、Xの評価を与える必要があります。
フィールディングは、REST APIのいくつかの属性をリストします。それらの一部は、SOおよび他のフォーラムでの一般的な慣行と一般的なアドバイスの両方に反するようです。例：
A REST APIは、初期URI（ブックマーク）および対象とする視聴者に適した標準化されたメディアタイプのセット（つまり、 APIを使用する場合があります）...
A REST APIは、固定リソース名または階層（クライアントとサーバーの明らかな結合）を定義してはなりません）...
A REST APIは、リソースの表現とアプリケーションの状態の駆動に使用されるメディアタイプの定義、または拡張リレーション名やハイパーテキスト対応マークの定義に、ほとんどすべての記述的努力を費やすべきです既存の標準メディアタイプのアップ...
「ハイパーテキスト」の考え方が中心的な役割を果たします。URI構造やHTTP動詞の意味よりもはるかに重要です。 「ハイパーテキスト」は、コメントの1つで定義されています。
私が[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は follow-up を投稿し、彼の議論はあまりに抽象的で、例に欠け、専門用語が豊富であるという批判に応えました。
他の人は、私が書いたものをより直接的に、または今日のいくつかの実際的な懸念に適用できる方法で解読しようとします。次のトピックに取り組んでいる、会議の準備をする、別の基準を書く、遠く離れた場所に旅行する、または給料を稼いだと感じさせるちょっとしたことをしているだけなので、多分忙しくないでしょう。
REST専門家が実践的な考え方を持つ2つの簡単な質問：フィールディングの発言をどのように解釈し、どのように文書化/実装するときにそれを実践するかREST API？
編集：この質問は、話している内容の名前がないと、何かを学ぶのがどれほど難しいかを示す例です。この場合の名前は、「アプリケーション状態のエンジンとしてのハイパーメディア」（HATEOAS）です。
あなたの説明はほとんどそれをカバーしていると思います。 URIは不透明な識別子であり、ほとんどの場合、ユーザーエージェントがアプリにアクセスするために使用するブックマークURIを超えて通信することはできません。
文書化に関しては、この質問はかなり何度も行われています。メディアタイプと、それに含まれるハイパーリンクコントロール（リンクとフォーム）、および必要に応じて相互作用モデル（AtomPubを参照）を文書化します。
URIまたはそれらの作成方法を文書化すると、それは間違っています。
あなたの解釈は私には正しいようです。フィールディングの制約は実際に適用できると思います。
RESTインターフェースを文書化する方法の良い例を誰かが公開することを本当に望んでいます。非常に多くの悪い例があり、ユーザーにポイントするためのいくつかの有効な例があれば非常に価値があります。
私はHATEOASに従って書かれたAPIの良い例を探していて、それを見つけるのに苦労していました（SunCloud APIとAtomPubの両方を「通常の」APIの状況に適用するのは難しいと思いました）。それで、適切なREST実装であることの意味についてのRoy Fieldingsのアドバイスに続く私のブログで現実的な例を作ってみました。事実にもかかわらず、例を思いつくのは非常に難しいことがわかりました原則としてはかなり単純です（WebページではなくAPIを操作するときに混乱するだけです）。Royが問題を抱えていたことがわかり、同意します。これは、APIを適切に実装するための考え方の変化にすぎません。
見てください： Restを使用したAPIの例
ほとんどの人が間違っているのは、（少なくとも私が思う）RESTの世界では、「Restインターフェース」を文書化しないことです。文書化するのはメディアタイプであり、サーバーまたはサービス。
興味のある方のために、実際にHATEOASの詳細な例を Sun Cloud API で見つけました。
URIの構築方法を指示する1つの例外は、ハイパーテキストレスポンスでURIテンプレートを送信することが許可されていることです。フィールドは、ハイパーテキストの他のフィールドを使用して、クライアントによって自動的に置き換えられます。これは通常、多くの帯域幅を節約することにはなりませんが、gzip圧縮はURIの繰り返し部分を十分に処理するため、これに悩まされることはありません。
RESTおよび関連するHATEOASに関するいくつかの良い議論：
ここ数年、RESTが出回っていますが、技術者はリソースの概念と、RESTfulとは何であるか、何がそうでないかを理解するようになりました。
Richardson Maturity Modelによれば、Roy Fieldingが意図したとおりに、APIのRESTfulを定義する4つのレベル（0〜3）があり、3つは本当にRESTful APIを意味します。
レベル0は、SOAPのような1つのエントリポイントURIがある場合です。
レベル1は、APIが異なるリソースを区別でき、複数のエントリポイントがあることを意味します-それでもSOAPのにおいがします。
レベル2は、主にGET、POST、DELETEというHTTP動詞を使用する場合です。これは、RESTが実際に登場するレベルです。
レベル3では、ハイパーメディアコントロールを使用して、APItrulyをRESTfulにします。
さらに読むための推奨リンク：
正解です。さらに、パターンがサーバーから受信したドキュメントからのものである限り（OpenSearchが適切な例です）、URIテンプレートはRESTfulアプリケーション内で完全に問題ありません。 URIテンプレートの場合は、テンプレートが使用されている場所と、テンプレートで予期されるプレースホルダーが何であるかを文書化しますが、テンプレート自体は文書化しません。バーンフリーデンの発言とは少し反対に、これは例外ではありません。
たとえば、私の仕事では内部ドメイン管理システムがあり、サービスドキュメントは2つのURIテンプレートを指定します。1つはドメインリソースの最良推測URIを生成するため、もう1つはドメインの可用性を照会するためのURIを構築するためです。ドメインコレクションをページングして、特定のドメインのURIが何であるかを把握することは引き続き可能ですが、管理するドメインの数が膨大であることを考えると、これはクライアントにとって実現不可能であるため、クライアントに何を推測するかを与えることができます。ドメインリソースのURIは、クライアントから見た実装の容易さ、およびサーバーからの帯域幅の点で非常に有利です。
あなたの質問に：私たちの規範的なドキュメントは、公開されたリソース、それらのリソースに対するさまざまなメソッドの影響、使用されている表現メディアタイプとそのスキーマ、およびそれらの表現のURIが指すリソースの種類です。
また、典型的なクライアント/サーバーの相互作用の例を示す、ドキュメントで言及されているURIを読みすぎないように免責事項を添付した非規範的な（参考）ドキュメントも含まれています。これは、かなり抽象的な規範的な文書を具体的な言葉で表現しています。
GET /foos/createFormを呼び出して、フォームフィールドの値を取得し、POST /foosを作成するときに指定する必要があるとします。さて、この特定のURL、つまりfooの作成に使用された1は、Fieldingの命題に従って送信アクションリンクとしてGET /foos/createFormの応答内で言及されるべきですよね？
次に、アクションをよく知られているHttp動詞からアクションにマッピングすることの利点は何ですか。