用語集

要点（TL;DR）:

• HTTPリクエストはJSON:APIの リソース に対して行われます。これを リソース オブジェクト と混同しないでください。
• クライアントが受け取るJSONオブジェクトは ドキュメント と呼ばれます。
• ドキュメントは常にJSONオブジェクトであり、 data キーの下に プライマリデータ を持ちます。
• そのキーの下のデータは リソースオブジェクト または リソース識別子オブジェクト と呼ばれます。
• 関連データをドキュメントに埋め込むように要求すると、それは 複合ドキュメント になります。
• 複合ドキュメントとは、トップレベルオブジェクトに included キーがあるものです。
• 多数の リソースオブジェクトを返すリソースは コレクションリソース と呼ばれます。
• 1つ のリソースオブジェクトを返すリソースは 個別リソース と呼ばれます。
• リソースオブジェクト 間 のリレーションシップに関する情報を返すリソースは リレーションシップリソース と呼ばれます。
• Drupalの用語では：
  • リソースオブジェクト -> エンティティ
  • リソース識別子オブジェクト -> エンティティ参照フィールドの項目
  • ドキュメント -> リクエスト/レスポンスのJSONペイロード

以下は、JSON:APIモジュールを説明する際に使用される用語と概念の簡単な説明です。

この用語集は JSON:APIの仕様 に非常に近いものですが、定義をDrupalに当てはめて説明しています。また、仕様に精通していなかったり、仕様の読み方 を知らない初心者にはわかりにくい、仕様の細かい部分にも踏み込んでいます。

これらの定義の多くは相互に関連しています。 このページの下部にある図 で、これらの用語が登場する文脈を示しています。

リソース

JSON:APIの レスポンスドキュメント を取得できる場所です。リソースはそのURL（ユニバーサルリソースロケータ）で見つけることができます。「リソースオブジェクト」と 混同しては いけません。リソースはアプリケーションのデータと一対一で対応するものでは ありません。

Drupalの用語では、JSON:APIのリソースはエンティティと同義では ありません。代わりに、リソースは 概念 のデータを取得できる場所です。例えば、その概念は「 node--article タイプのリソースオブジェクトのコレクション」だったり、「特定の記事ノードの field_tags エンティティ参照フィールドの表現」だったりします。

レスポンスドキュメント

JSON:APIの リソース から返されるJSONエンコードされたレスポンス ボディ です。データまたはエラーがHTTPクライアントに伝達される「封筒」です。 トップレベルオブジェクト と呼ばれることもあります。ドキュメントが included ドキュメントメンバー を持つ場合、複合ドキュメント と呼ばれます。

複合ドキュメント

 included ドキュメントメンバー を含む レスポンスドキュメント です。複合ドキュメントは、レスポンスドキュメントのプライマリデータに加えて関連する リソースオブジェクト を埋め込むことで、HTTPリクエストを削減するために使用できます。複合ドキュメントは、リクエストのURLに include クエリパラメータを追加することで要求できます。

エラードキュメント

1つ以上の エラーオブジェクト を含む errors ドキュメントメンバー を含む レスポンスドキュメント です。 data ドキュメントメンバーを含むことはありません。エラードキュメントを含むレスポンスのHTTPステータスコードは、常に4xxまたは5xxレベルのコードになります。

個別リソース

 レスポンスドキュメント の data  メンバー として 単一の リソースオブジェクト を含む リソース です。十分な認可があれば、このリソースは読み取りと変更が可能です。Drupalの用語では、このリソースは個々のエンティティの「表示」「更新」「削除」に使用できます。 エンティティの「作成」には使用できません。

コレクションリソース

 レスポンスドキュメント の data  メンバー として 多数の リソースオブジェクト を含む リソース です。十分な認可があれば、このリソースは読み取りと書き込みが可能です。 これらのリソースは、 ページ分割、 フィルタリング、 ソート ができます。 Drupalの用語では、このリソースは新しいエンティティの「作成」に使用できます。 コレクション内のエンティティの「更新」や「削除」には使用できません。

リレーションシップリソース

 レスポンスドキュメント のトップレベルオブジェクトとして リレーションシップオブジェクト を含む リソース です。それぞれが リソースオブジェクト から別のリソースオブジェクトへの参照を表す1つ以上の リソース識別子オブジェクト を含みます。十分な認可があれば、このリソースは読み取りと変更が可能です。Drupalの用語では、このリソースは単一のエンティティ参照フィールドの項目の「表示」または「編集」に使用できます。

関連リソース

 レスポンスドキュメント の data  メンバー として1つ以上の リソースオブジェクト を含む特殊な コレクションリソース である リソース です。このコレクション内のリソースオブジェクトは、参照するリソースオブジェクト上のリレーションシップの対象です。このリソースは読み取り専用です。Drupalの用語では、このリソースはエンティティ参照フィールドによって 参照されている エンティティの「表示」に使用できますが、それらのエンティティの「更新」や、それらを参照するエンティティ参照フィールドの「編集」には使用できません。

ドキュメントメンバー

JSON:APIのトップレベル ドキュメント の一部であるJSONオブジェクトです。これらのオブジェクトは常に、仕様で定義されたキー（例： jsonapi、 data、 included、 errors）の下に配置されます。

リソースオブジェクト

エンティティをJSONオブジェクトとして表現したものです。「リソース」と 混同しては いけません。 こちら はアプリケーションのデータと一対一で対応します。

属性オブジェクト

それが定義されている リソースオブジェクト に関する情報を表すJSONオブジェクトです。属性には任意の有効なJSON値を含めることができます。Drupalの用語では、このオブジェクトはエンティティ参照ではないすべてのエンティティフィールド値を表します。

リレーションシップオブジェクト（複数形）

それが定義されている リソースオブジェクト から他のリソースオブジェクトへの参照を含むJSONオブジェクトです。リレーションシップ（単数形）オブジェクトである多くのメンバーを含みます。Drupalの用語では、このオブジェクトはすべてのエンティティ参照フィールド値を表します。

リレーションシップオブジェクト（単数形）

それが定義されている リソースオブジェクト から他のリソースオブジェクトへの参照を表すJSONオブジェクトです。これは resource identifier objects（リソース識別子オブジェクト）を含み、それぞれが別のリソース オブジェクトへの単一のリレーションシップを表します。Drupalの用語では、このオブジェクトは単一のエンティティ参照フィールドを表します。

リソース識別子オブジェクト

ある リソースオブジェクト から別のリソースオブジェクトへのリレーションシップを表す非常にシンプルなJSONオブジェクトです。「リソースオブジェクト」と 混同しては いけません。 type キーと id キーのみを含み、オプションでそのリレーションシップに関する情報を保持する meta キーを含むことができます。特に、 links メンバーは含まないことに注意してください。

これは「リソースリンケージ」を提供し、 複合ドキュメント では、HTTPクライアントが リレーションシップオブジェクト を、複合ドキュメントの included メンバー内の参照された リソースオブジェクト と関連付けることができます。

リンクオブジェクト

他の リソース へのハイパーリンクを含むJSONオブジェクトです。

エラーオブジェクト

リクエストの処理中に発生したエラーを表すJSONオブジェクトです。これらは、クライアントエラー、バリデーションエラー、サーバーエラーなどを表すことができます。

記事：Drupal ドキュメンテーションより。