包含リソースが含まれる応答のペイロード構造

このチュートリアルの前提事項は、Postman の環境を設定してあり適切なサンプルデータセットを用意していることです。詳細については、チュートリアル：Postman 環境のセットアップを参照してください。

包含リソースが含まれる応答の高度な構造は、以下に示すとおりです。包含リソースに特に関係する情報は、太字で表示されます。（注意：JSON ではコメントをサポートしません。ただし、コードを明確化するため、擬似コメントが追加されています。各擬似コメントの前にはハッシュタグ（#）が付きます。）

{
    "count": N,                        # Number of resources is payload
    "data": [                          # Details for each resource
        {                              # Resource 1 begins here
            "attributes": {            # Resource 1 name/value pairs
                "propertyName": "propertyValue",
                ... },
            "checksum": "val",         # Resource 1 checksum value
            "links": {                 # Links relevant to Resource 1
                ... },
            "related": {              # List of resources related to R1
                "resourceType": {      # Related resource type
                    "count": NN,       # Number of related resources for R1
                    "data": [
                        {              # First resource related to R1 starts
                            "id": "relatedResourceID",
                            "type": "resourceType"
                        },             # First resource related to R1 ends
                        ...            # Other resources related to R1
                    ] } }
        },                             # Resource 1 ends here
        {                              # Resource 2 begins here
            "attributes": {            # Recourse 2 name/value pairs
                "propertyName": "propertyValue",
                ... },
            "checksum": "val",         # Resource 2 checksum value
            "links": {                 # Links relevant to Resource 2
                ... },
            "related": {               # List of resources related to R2
                "resourceType": {      # Related resource type
                    "count": NN,       # Number of related resources for R2
                    "data": [
                        {              # First resource related to R2 starts
                            "id": "relatedResourceID",
                            "type": "resourceType"
                        },             # First resource related to R2 ends
                        ...            # Other resources related to R2
                    ] } }
        },                             # Resource 2 ends here
        ... ],                         # Resources 3 to N
    "links": {                         # Links relevant to collection
             ...
        },
    "included": {                      # List of related resources
        "resourceType": [              # First related resource type
            {
                "attributes": {        # Related resource 1 start
                    ...                # Related resource 1 name/value pairs
                    "id": " relatedResourceID ",
                    ... },
                "checksum": "0",       # Related resource 1 checksum value
                "links": { ... }       # Links relevant to Related resource 1
            },
            ...                        # Related resources 2 to end
    ] }
}

各リソースには、以下を特定する追加の related セクションがあります。

• 包含リソースの数、および
• 包含リソースの ID

例えば、以下のコードスニペットは、すべてのアクティビティと関連の備考・経緯のクエリの応答からの抜粋です。アクティビティ xc:44 には備考・経緯が 1 つ含まれ、その ID は xc:55 です。

{
    "attributes": {
        ...
        "id": "xc:44",
        ...
        "subject": "Check coverage"
    },
    "checksum": "2",
    "links": {
        ...
    },
    "related": {
        "notes": {
            "count": 1,
            "data": [
                {
                    "id": "xc:55",
                    "type": "Note"
                }
            ]
         }
      }
},

GET で included クエリパラメータを使用するが、関連リソースが存在しない場合でも、related セクションは引き続き表示されます。ただし、カウントは 0、data セクションは空白です。例：

"related": {
    "notes": {
        "count": 0,
        "data": []
    }
}

GET で included クエリパラメータを省略すると、related セクションが応答ペイロードから省略されます。

各応答には included セクションがあり、応答ペイロードの末尾に表示されます。このセクションには、主要リソースの各包含リソースについての詳細情報が一覧表示されます。

例えば、以下のコードスニペットは、前出の例の included セクションのものです。

"included": {
    "Note": [
        {
        "attributes": {
            "author": {
                "displayName": "Betty Baker",
                "id": "demo_sample:8"
            },
            "bodySummary": "Main contact is on vacation 03/20",
            "confidential": false,
            "createdDate": "2020-03-30T23:11:33.346Z",
            "id": "xc:55",
            "relatedTo": {
                "displayName": "235-53-373871",
                "id": "demo_sample:8002",
                "type": "Claim"
            },
            "subject": "Main contact is on vacation 03/20",
            "topic": {
                "code": "general",
                "name": "General"
            },
        "updateTime": "2020-03-30T23:12:08.892Z"
        },
            "checksum": "0",
            "links": {
                "self": {
                    "href": "/common/v1/notes/xc:55",
                    "methods": [
                        "get",
                        "patch"
                    ]
                }
            }
        }
    ]
},

アクティビティ xc:44 には備考・経緯が 1 つ含まれていることを思い出してください。含まれている備考・経緯の ID は xc:55 です。included セクションに表示される備考・経緯は、アクティビティ xc:44 に関連する備考・経緯です。

特定のエンドポイントに対して、include オプションのいくつかは、プライマリリソースごとにリソースのコレクションを返します。それ以外の include オプションは、プライマリリソースごとに 1 つのリソースを返します。

最初のケースの例は、GET /claims/{claimId}?include=contacts です。この呼び出しで返される内容は、特定のクレーム ID を持つクレームと、そのクレームに関連するすべてのクレーム連絡先です。理論的には、プライマリリソース（特定のクレーム ID を持つクレーム）ごとに、関連するリソース（クレーム連絡先）が複数存在します。

2 番目のケースの例は、GET /claims/{claimId}?include=mainContact です。この呼び出しで返される内容は、特定のクレーム ID を持つクレームと、主要な連絡先として指定されているクレーム連絡先です。プライマリリソース（特定のクレーム ID を持つクレーム）ごとに、関連するリソース（主要なクレーム連絡先）が 1 つのみ存在します。

GET /claims/{claimId}?include=contacts,mainContact のように、複数の include オプションを指定することもできます。この場合、クレームごとに、関連セクションが、すべての関連連絡先の ID を指定し、さらに、主要な連絡先の ID も明示的に特定します。

一般ルールとして、include オプションが複数指定されている場合、プライマリリソースごとにリソースのセットが返されます。include オプションが単数指定されている場合、プライマリリソースごとに 1 つのリソースが返されます。

エンドポイントごとに、エンドポイントの API 定義を参照することで、含めることができるリソースを決定できます。データエンベロープのモデルで名前の末尾が「...Inclusions」になります。このデータエンベロープでリストされるすべてのリソースに含めることができる場合は、そのタイプのリソースに対してクエリを実行するときです。

例えば、Common API では、GET /activities のモデルは、ActivityResponseInclusions 要素を参照します。この要素には、1 つの子要素である Note があります。アクティビティのクエリで含めることができる要素の唯一のタイプが notes であることを意味します。

特定のエンドポイントで包含に対してサポートされていないリソースタイプを含めようとすると、API から 400 エラーコードおよびメッセージが返されます。例えば、GET /activities?include=users を実行しようとした場合、以下のメッセージが返されます。

"userMessage": "Bad value for the 'include' query parameter - The requested
inclusions '[users]' are not valid for this resource. The valid options are [notes]."