Anforderungseinschluss

Anforderungseinschluss ist eine Technik für POSTs und PATCHs, bei der der Aufruf Folgendes umfasst:

  • Eine einzelne übergeordnete Anforderung, die eine Ressource erstellt oder ändert
  • Eine oder mehrere untergeordnete Anforderungen, die mit der übergeordneten Ressource verbundene Ressourcen erstellen oder ändern

Wenn entweder die übergeordnete Anforderung oder eine untergeordnete Anforderung fehlschlägt, schlägt die gesamte Anforderung fehl.

Die übergeordnete Ressource wird oft als Stammressource bezeichnet. Die Stammressource wird im data-Abschnitt der Nutzdaten angegeben. Die zugehörigen Ressourcen werden im included-Abschnitt der Nutzdaten angegeben.

Beispielsweise kann ein Aufrufer ein einzelnes POST /claims verwenden, um einen neuen Schadenfall, eine Reihe von ClaimContacts für diesen Schadenfall, eine Reihe von Vorfällen für diesen Schadenfall und eine Reihe von Teilschäden für diesen Schadenfall zu erstellen.

Um den Anforderungseinschluss zu verwenden, muss Folgendes zutreffen:

  • Für die Stammressource muss ein POST- oder PATCH-Endpunkt vorhanden sein.
  • Dieser Endpunkt muss über die untergeordnete Ressource als Teil des included-Abschnitts verfügen.
  • Für die untergeordnete Ressource muss auch ein POST- oder PATCH-Endpunkt vorhanden sein.

Die Syntax für den Anforderungseinschluss variiert leicht, je nachdem, ob die Beziehung zwischen der Stammressource und der eingeschlossenen Ressource eine „einfache Übergeordnet/Untergeordnet-Beziehung“ oder eine „benannte Beziehung“ ist.

Syntax für einfache hierarchische Beziehungen

In den meisten Fällen ist die Beziehung zwischen der Stammressource und einer eingeschlossenen Ressource eine einfache hierarchische Beziehung. Beispiele hierfür sind:

  • Eine Aktivität und ihre Notizen
  • Einen Schadenfall und seine Vorfälle

Wenn Sie die Einschließung von Anforderungen für einfache hierarchische Beziehungen verwenden, hat das JSON die folgende Struktur:

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

Abschnitt data

Der Abschnitt data enthält Informationen über die Stammressource, z. B. ihre attributes. (Bei PATCHs kann der Abschnitt data auch einen Prüfsummenwert für die Stammressource enthalten.)

Abschnitt included

Der Abschnitt included besteht aus einem oder mehreren Unterabschnitten eingeschlossener Ressourcen. Jeder Unterabschnitt beginnt mit dem Namen des Ressourcentyps. Anschließend können eine oder mehrere Ressourcen dieses Typs angegeben werden. Für jede Ressource müssen Sie die folgenden Informationen angeben werden:

  • attributes der Ressource
  • method und uri zum Erstellen oder Ändern der Ressource.

Felder method und uri.

Die Anforderungseinbindung umfasst einen einzelnen Aufruf eines einzelnen Endpunkts. Intern verwenden die System-APIs jedoch mehrere Endpunkte, um den Aufruf auszuführen. Für jede eingeschlossene Ressource müssen Sie den für diese Ressource relevanten Vorgang und URI angeben.

Beispiel: Angenommen, Sie schreiben einen Aufruf "POST /claim", um einen Schadenfall und eine Notiz zu erstellen. Die Notiz ist die included Ressource. Der Abschnitt "included" würde Code ähnlich dem folgenden enthalten:

"included": {
  "Note": [
    {
      "attributes": {
          ...
      },
      "method": "post",
      "uri": "/claim/v1/claims/this/notes"
    }
  ]
}

Damit wird angegeben, dass zum Erstellen der Notiz der Endpunkt POST /claim/v1/claims/{claimId}/notes verwendet wird.

Der URI muss mit dem API-Namen beginnen, z. B. "/claim/v1".

Der URI muss auch die ID der Stammressource angeben. Wenn die Stammressource und die eingeschlossenen Ressourcen gleichzeitig erstellt werden, hat die Stammressource noch keine ID. Daher wird das Schlüsselwort this im URI zur Darstellung der ID der Stammressource verwendet.

Beispiel für die Einschließung von Anforderungen für einfache hierarchische Beziehungen

Die folgenden Nutzdaten sind ein Beispiel für die Erstellung eines Schadenfalls und einer Notiz für den Schadenfall. Bei den Nutzdaten wird davon ausgegangen, dass eine Police mit der Nummer "Schadenerstmeldung - Police" existiert. Weitere Informationen zur Erstellung von Policen finden Sie unter Ausführen von Schadenerstmeldungen.

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

{
  "data" : {
    "attributes": {
      "lossDate": "2020-02-01T07:00:00.000Z",
      "policyNumber": "FNOL-POLICY"
	}
  },
  "included": {
    "Note": [
      {
        "attributes": {
            "subject": "Initial phone call",
            "body": "Initial phone call with claimant"
        },
        "method": "post",
        "uri": "/claim/v1/claims/this/notes"
      }
    ]
  }
}

Syntax für benannte Verhältnisse

In einigen Fällen ist das Verhältnis zwischen der Stammressource und einer eingeschlossenen Ressource mehr als nur ein hierarchisches Verhältnis. Es handelt sich um ein "benanntes Verhältnis", bei dem das Verhältnis eine spezielle Bezeichnung hat.

Beispielsweise hat jeder Schadenfall einen "Melder". Dies ist der ClaimContact, der den Schadenfall zuerst an den Versicherer gemeldet hat. Ein Schadenfall kann eine beliebige Anzahl untergeordneter ClaimContacts haben, aber nur einer dieser ClaimContacts kann als Melder bezeichnet werden.

Wenn Sie die Einschließung von Anforderungen für benannte Verhältnisse verwenden, hat das JSON die folgende Struktur. Die Zeilen, die für einfache hierarchische Verhältnisse nicht erforderlich sind, aber für benannte Verhältnisse erforderlich sind, werden fett dargestellt:

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

Abschnitt data

Der Abschnitt data enthält Informationen über die Stammressource, z. B. ihre attributes. (Bei PATCHs kann der Abschnitt data auch einen Prüfsummenwert für die Stammressource enthalten.)

Der Abschnitt data enthält auch das Feld, das die Beziehung zur untergeordneten Ressource benennt. Dieses Feld ist auf eine Referenz-ID gesetzt. Der Wert dieser Referenz-ID ist willkürlich. Er kann ein beliebiger Wert sein, solange der Wert auch mit der untergeordneten Ressource im Abschnitt included angezeigt wird.

Abschnitt included

Der Abschnitt included besteht aus einem oder mehreren Unterabschnitten eingeschlossener Ressourcen. Jeder Unterabschnitt beginnt mit dem Namen des Ressourcentyps. Anschließend können eine oder mehrere Ressourcen dieses Typs angegeben werden. Für jede Ressource müssen Sie die folgenden Informationen angeben werden:

  • attributes der Ressource
  • method und uri zum Erstellen oder Ändern der Ressource.

Feld refid

Jede included Ressource muss Feld refid enthalten. Dieses Feld muss auf dieselbe beliebige Referenz-ID gesetzt werden, die im Abschnitt data verwendet wird. Die System-APIs verwenden refids, um zu ermitteln, welche untergeordnete Ressource im Abschnitt included das benannte Verhältnis zur Stammressource hat.

Felder method und uri.

Die Anforderungseinbindung umfasst einen einzelnen Aufruf eines einzelnen Endpunkts, aber die System-APIs verwenden intern mehrere Endpunkte, um den Aufruf auszuführen. Für jede eingeschlossene Ressource müssen Sie den für diese Ressource relevanten Vorgang und URI angeben.

Beispiel: Angenommen, Sie schreiben einen POST /claims-Aufruf, um einen Schadenfall zu erstellen, und einen ClaimContact, der der "Melder" ist. Der ClaimContact ist die Ressource included. Der Abschnitt "included" würde Code ähnlich dem folgenden enthalten:

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

Damit wird angegeben, dass zum Erstellen des ClaimContact der Endpunkt /claim/v1/claims/{claimId}/contacts verwendet wird.

Der URI muss mit dem API-Namen beginnen, z. B. "/claim/v1".

Der URI muss die ID der Stammressource angeben. Wenn die Stammressource und die eingeschlossenen Ressourcen gleichzeitig erstellt werden, hat die Stammressource noch keine ID. Daher wird das Schlüsselwort this im URI zur Darstellung der ID der Stammressource verwendet.

Beispiel für die Einschließung von Anforderungen für benannte Beziehungen

Die folgenden Nutzdaten sind ein Beispiel für die Erstellung eines Schadenfalls und eines ClaimContact für den Schadenfall, dessen Verhältnis "Reporter" lautet. Bei den Nutzdaten wird davon ausgegangen, dass eine Police mit der Nummer "Schadenerstmeldung - Police" existiert. Weitere Informationen zur Erstellung von Policen finden Sie unter Ausführen von Schadenerstmeldungen.

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"
      }
    ]
  }
}

Zusätzliches Verhalten beim Einschließen von Anforderungen

PATCH und POST in einer einzigen Anforderung

Wenn Sie einen POST mit Anforderungseinschluss ausführen, muss der Vorgang für jede eingeschlossene Ressource ebenfalls POST sein.

Wenn Sie ein PATCH mit Anforderungseinschluss ausführen, kann der Vorgang für eine eingeschlossene Ressource entweder POST oder PATCH sein.

  • Wenn Sie eine vorhandene Ressource ändern und eine neue zugehörige Ressource erstellen möchten, lautet der POST-Vorgang der enthaltenen Ressource.
  • Wenn Sie eine vorhandene Ressource ändern und eine vorhandene zugehörige Ressource ändern möchten, ist der Vorgang der enthaltenen Ressource PATCH.

Anforderungen als Einheit erfolgreich oder fehlerhaft

Wenn ein POST oder PATCH die Einschließung von Anforderungen verwendet, kann entweder der Vorgang für die Stammressource oder der Vorgang für eine der eingeschlossenen Ressourcen fehlschlagen. Wenn ein Vorgang fehlschlägt, schlägt die gesamte Anforderung fehl, und keines der Objekte ist POSTed oder PATCHed.

Eingeschlossene Ressourcen können nicht auf andere Ressourcen als die Stammressource verweisen

Wenn Sie die Einschließung von Anforderungen verwenden, muss jede eingeschlossene Ressource ihren eigenen Vorgang und URI angeben. Es wird erwartet, dass der URI mit dem Schlüsselwort this auf die Stammressource verweist. Dadurch wird sichergestellt, dass die eingeschlossene Ressource mit der Stammressource verbunden ist, wenn es sich um POSTed oder PATCHed handelt.

Angenommen, ein POST erstellt einen Schadenfall und eine Notiz. Der URI für den Teilschaden hätte einen Wert wie "/claim/v1/claims/this/notes".

Aus Syntaxperspektive könnten Sie versuchen, eine eingeschlossene Ressource nicht an die Stammressource, sondern an eine andere vorhandene Ressource anzuhängen. Anstatt beispielsweise auf die Stammressource zu verweisen, könnte der URI für die Notiz auf einen vorhandenen Schadenfall verweisen, z. B. "/claim/v1/claims/cc:200/notes". In diesem URI heißt es: "Erstellen Sie eine Notiz und fügen Sie sie nicht an die Stammressource dieses POSTs an, sondern an den vorhandenen Schadenfall cc:200".

Die System-APIs lassen dies nicht zu. Jeder Versuch, eine eingeschlossene Ressource auf etwas Anderes als die Stammressource POST- oder PATCH-fähig zu machen, führt dazu, dass der Vorgang fehlschlägt.