名前付き関係の構文

ルートリソースと包含リソースとの関係は単なる親／子関係以上のものである場合があります。それが、関係に特別な指定またはラベルを含む「名前付き関係」です。

例えば、すべてのクレームには「報告者」が含まれます。これは、保険会社に最初にクレームを報告したクレーム連絡先です。クレームには、任意の数の子クレーム連絡先を指定できますが、「報告者」というラベルを付けることができるクレーム連絡先はこれらの中の 1 つだけです。

名前付き関係に要求包含を使用している場合は、JSON の構造は次のようになります。単純な親／子関係には必要ないものの、名前付き関係には必要な行は太字で表示されています。

{
  "data" : {
    "attributes": {
      "<relationshipField>": "<arbitraryRefId>"
      ...
    }
  },
  "included": {
    "<resourceType>": [
      {
        "attributes": {
          ...
        },
        "refid": "<arbitraryRefId>",
        "method": "post",
        "uri": "/../this/..."
      }
    ]
  }
}

data セクション

data セクションには、attributes などのルートリソースに関する情報が含まれています。（パッチの場合は、data セクションにルートリソースのチェックサム値を含めることもできます。）

data セクションにはまた、子リソースとの関係に名前を付けるフィールドを含めることもできます。このフィールドは、参照 ID に対して設定できます。この参照 ID の値は任意です。値が included セクションの子リソースにも指定されているかぎり、任意の値が可能です。

included セクション

included セクションは、包含リソースの 1 つ以上のサブセクションで構成されます。各サブセクションはリソースタイプ名から始まります。その後、該当のタイプのリソースを 1 つ以上指定できます。各リソースについて、以下を指定します。

  • リソースの attributes
  • リソースを作成または変更するための method と uri

refid フィールド

各 included リソースには、refid フィールドを指定する必要があります。このフィールドは data セクションで使用されている任意の参照 ID と同じ値に設定する必要があります。システム API は refid を使用して、included セクションのどの子リソースにルートリソースとの名前付き関係があるのかを識別します。

method フィールドと uri フィールド

要求包含では、1 つのエンドポイントに対して 1 つの呼び出しを指定しますが、内部では、システム API が複数のエンドポイントを使用してその呼び出しを実行します。すべての包含リソースについて、そのリソースに関連する操作と URI を指定する必要があります。

例えば、クレームと「reporter」であるクレーム連絡先を作成するために POST /claims 呼び出しを記述しているとします。このクレーム連絡先が included リソースになります。included セクションには、次のようなコードが含まれます。

"included": {
  "ClaimContact": [
    {
      "attributes": {
        ...
      },
      "refid": "...",
      "method": "post",
      "uri": "/claim/v1/claims/this/contacts"
    }
  ]
}

このコードは、ClaimContact を作成するために、POST /claim/v1/claims/{claimId}/contacts エンドポイントを使用することを指定しています。

URI は「/claim/v1」などの API 名から始めます。

ここではルートリソースの ID も指定する必要があります。ルートリソースと包含リソースを同時に作成している場合は、ルートリソースにはまだ ID がありません。したがって、ルートリソースの ID を表すためにキーワード this を URI に使用します。

ここではルートリソースの ID も指定する必要があります。ルートリソースと包含リソースを同時に作成している場合は、ルートリソースにはまだ ID がありません。したがって、ルートリソースの ID を表すためにキーワード this を URI に使用します。

名前付き関係の要求包含の例

次のペイロードは、クレームと関係が「reporter」であるクレームのクレーム連絡先の作成例です。このペイロードでは、番号が「FNOL-POLICY」の既存の保険契約があることを前提としています。保険契約の作成の詳細については、事故受付の実行を参照してください。

POST http://localhost:8080/cc/rest/claim/v1/claims

{
  "data" : {
    "attributes": {
      "lossDate": "2020-02-01T07:00:00.000Z",
      "policyNumber": "FNOL-POLICY",
      "reporter": {
            "refid": "robertFarley"
        }
	}
  },
  "included": {
    "ClaimContact": [
      {
        "attributes": {
          "firstName": "Robert",
          "lastName": "Farley",
          "contactSubtype": "Person"
        },
        "refid": "robertFarley",
        "method": "post",
        "uri": "/claim/v1/claims/this/contacts"
      }
    ]
  }
}