あなたが探しているものは、最近では HATEOAS API と呼ばれています。例については、この質問を参照してください: HATEOAS (REST アーキテクチャ) の実際の例
Roy Fielding によって最初に定義された ReST アーキテクチャ スタイルは、アーキテクチャの制約の 1 つとして「アプリケーション状態のエンジンとしてのハイパーテキスト」を規定しています。しかし、人々が「RESTful API」を「HTTP 動詞を正しく使用する」ことと比較し始めたとき、この概念は多かれ少なかれ「翻訳で失われました」(運が良ければもう少し)。(編集: 私の主張に信憑性を与えることは、 RESTful プログラミングとは正確には何ですか?の 1 番目と 2 番目に高い回答です。最初の話は HTTP 動詞についてのみです)。
あなたの質問に対するいくつかの考え: (主に、主題が私を魅了し続けているため)
HATEOAS では、正確な意味を持つ標準化されたメディア タイプが非常に重要です。これに関する一般的な理解とツールの恩恵を受けるために、可能な場合は既存のメディア タイプを再利用することが最善であると一般的に考えられています。一般的な方法の 1 つは XML を使用することです。これは、XML スキーマまたは名前空間を使用して、データの一般的な構造とセマンティクスを定義する方法の両方を提供するためです。HATEOAS を考えると、XML 自体は多かれ少なかれ無意味です。同じことが JSON にも当てはまります。
リンクをサポートするには、リンクを「ネイティブに」サポートするメディア タイプ (つまりtext/html、application/xhtml+xmlたとえばXLINK。application/jsonJSON 自体にはメタデータを定義する事前定義された場所がないため、使用できないと思います。jsonに基づいてメディアタイプを設計することは可能だと思います-それを呼び出しますapplication/x-descriptive-json- 返される JSON ドキュメントが「header」および「body」プロパティで構成されている必要があることを前もって定義し、ヘッダーにはさらに指定されたメタデータを含めることができます。埋め込みリンクをサポートするためだけに、JSON のメディア タイプを設計することもできます。単純なメディア タイプで、拡張性が低い。私が説明した両方のものが何らかの形ですでに存在していても、私は驚かないでしょう.
ブラウザとブラウザ以外のクライアントの両方に親切にするために必要なのは、Acceptヘッダーを尊重することだけです。text/html を要求するクライアントは、text/html に本当に満足していると想定する必要があります。text/htmlこれは、ブラウザ以外の API エントリ ポイントのメディア タイプとして使用しないための引数になる可能性があります。原則として、リンクだけが必要な場合でも機能すると思います。優れた HTML マークアップは、ブラウザ以外のクライアントでも十分に利用できます。HTML は、 を通じてrel="next"、ページングを行う方法も定義しますrel="previous"。
ブラウザーとブラウザー以外の両方で単一のメディア タイプが持つ 3 つの最大の問題は次のとおりです。
- すべてのサイト html がブラウザー以外での消費を考慮して出力されるようにする必要があります。つまり、十分なメタデータを埋め込む必要があります。おそらくいくつかの場所に隠しリンクを追加します。視覚障害者のアクセシビリティについて考えるのと少し似ていますが、今は、英語や自然言語を読めない消費者向けに設計しています。:)
- ブラウザ以外のクライアントには本質的に関係のない多くのマークアップとコンテンツが存在する可能性があります。ヘッダーとフッターのテキストを繰り返すことを考えてみてください。ナビゲーション エリアはそのようなものです。
- HTML には、必要な表現力が欠けているだけかもしれません。原則として、あなたのサイトに固有のいくつかの規則を「考え出す」とすぐに（つまり
rel="original-image、フルサイズの元の画像へのリンクを意味します）、厳密にHATEOSを行うことはもうありません（少なくとも、それは私の理解です） ）。HTML には、要素に新しい意味を定義する余地がありません。XML はそうです。
XHTML は XML であるため、名前空間を介して新しい種類の要素を指定できるため、問題 3 の回避策は XHTML を使用することです。
@robert_b_clarke が Microformats に言及しているのを見ました。これは、この議論に関連しています。これは実際、人間以外のエージェントのアクセシビリティを改善しようとする 1 つの方法です。技術的な観点から見たこれに関する主な問題は、基本的に「帯域外」の情報に依存していることです。マイクロフォーマットはtext/html仕様の一部ではありません。ある意味では、「タイプ A で ID X のリソースがあるとしたら、mysite.com/A/X でアクセスできます」と言うことに匹敵します。私が挙げた例はrel=original-image、マイクロフォーマットとも言えます。しかし、それは道のりです。「API ドキュメントに記載してください: 私たちは適切にフォーマットされた text/html を提供しています。私たちの text/html には、次のマイクロフォーマットも埋め込まれています: ...」 独自のものを定義することもできます。
次のプレゼンテーションは、HATEOAS の優れた現実的な説明だと思います
。
編集：
HTML5の microdataについて読んだだけです (@robert_b_clarke のおかげで)。HTML5 は、標準の HTML タグで可能な以上の追加情報を提供する方法を提供しているようです。私が書いた日付を考えてみましょう。:) 編集 編集: これは下書きにすぎません。;)
編集 2
「記述的 JSON」形式について: これは発表されたばかりですhttp://jsonapi.org/。彼らは独自の MIME タイプを申請しました。これは Yehuda Katz (Ember.js) と、 Designing Hypermedia APIを書いている Steve Klabnibによるものです。