クライアントがとにかくそれを利用するのに十分に進歩していないとき、REST APIの「発見可能性」の必要性は何ですか？

私が見たさまざまな講演やRESTでスキャンしたチュートリアルは、「発見可能性」と呼ばれるものを強調しているようです。私の限られた理解では、この用語は、クライアントがアクセスできることを意味するようですhttp://URL-できることのリストを自動的に取得します。

私が理解できないのは、「ソフトウェアクライアント」は人間ではないということです。これらは、提供されたリンクをどうするかを正確に理解するための直感的な知識を持たない単なるプログラムです。Webサイトにアクセスして、表示されたテキストとリンクを理解し、それに基づいて行動できるのは人々だけです。

クライアントの人間の開発者が提示されたリソースを実際に実験しない限り、そのような発見可能なURLにアクセスするクライアントコードが実際に何もできないとき、発見可能性のポイントは何ですか？これは、ドキュメンテーションマニュアルで利用可能な機能のセットを定義するのとまったく同じように見えますが、異なる方向からだけで、実際には開発者のためにより多くの作業を伴います。なぜ、実際のRESTリソースの外部のドキュメントで実行できることを事前定義するこの2番目のアプローチが劣っていると考えられますか？

発見可能性の必要性は関係ないかもしれませんが、発見可能性を可能にするリンクはより多くの目的に役立ちます。これらの中で最も重要なことは、私の考えでは、クライアントへの応答に完全なURIを提供することは、クライアントがURIを「作成」する必要がないことを意味します。これは、URIがどのように構成されているかについての知識をクライアントが必要としないことを意味します。そして、それにより、サーバー開発者は、古いクライアントがまだURIを構造化する古い方法に依存していることを考慮する必要がないため、必要に応じてURIスキームを変更できます。

「クライアント」はそれを利用するほど高度ではないかもしれませんが、クライアントのユーザーはそれを利用できます。結局のところ、クライアントはWebブラウザーのような単純なものになります。発見可能性とは、人々がAPIを学び、使用できるようにすることです。

たとえば、Jenkins（CIサーバー）にはRESTのようなインターフェースがあります。任意のページに移動し、「/ api」を使用してURLを後置すると、実行可能なすべてを説明するページが表示されます。APIの学習が簡単になります。たとえば、http： //ci.jruby.orgはjrubyのjenkinsサーバーに移動し、http： //ci.jruby.org/api はその特定のページのapiに移動します。

少し前に、非常に理解しづらいドキュメンテーションを備えたAPIを使用できるようになりました。

サーバーから実際の返信を受け取ることができたら、ドキュメントをサーバーの返信と比較し、それを使用してドキュメントを解読することができました（そして、それは正しい用語であると解読しました）。問題は、仕様に従って正確に正しくないリクエストがサーバーに送信された場合、エラーが発生し、読めないドキュメントでは、正しいリクエストを送信する方法がほとんど不可能であることでした。また、APIドキュメントには異なるバージョンがあり、互いに同意していなかったため、おそらくAPI自体に同意していませんでした。それは助けにはなりませんでした。

サーバーに送信できるコマンドが1つあり、可能なすべてのコマンドのリストとそれらを正確に送信する方法があれば、それは非常に役に立ちました。発見可能性はクライアントだけでなく、ソフトウェア開発者にとっても有用です。

注：私はこのテーマの専門家ではありませんが、数年前に「レスト」の人々の解釈のさまざまなニュアンスを調整しようとする同様のプロセスを経験しました。これは、時間。

私の理解では、これは、Roy Fieldingのアプリケーション状態のエンジンである「HATEOAS」としてのハイパーメディアに由来します。これは、「セマンティックWeb」のアイデアを実現します。

それで...基本的に、そして私が理解しているように、あなたはあなたのRESTfulアプリケーションを基本的に自己記述的にし、消費者があなたのコンテンツ/機能を消費するための正式な契約の事前知識を必要としないようにします。デフォルトのルートエンドポイントからエンゲージして、消費者が対話するときにアプリが提供するコンテキストに関連するリンクをたどることができます。もちろん、消費者は人または全身性のエージェントであり得る。

よく知られた契約に従って消費者が事前の知識と呼び出しを必要とするCRUD操作にマッピングされたきれいなURLに「REST」を使用している場合、Roy Fieldingはそれを真にRESTfulではないとみなします。

それは、RESTフレーバーのRPCサービスのセットアップが役に立たないということではありません/より精巧なRPCモデルよりも改善され、制限された/制御された使用に適しています/本当にRESTではありません。