Nutzdatenstruktur für eine Antwort mit eingeschlossenen Ressourcen

In diesem Lernprogramm wird davon ausgegangen, dass Sie Postman in Ihrer Umgebung mit dem korrekten Beispieldatensatz eingerichtet haben. Weitere Informationen finden Sie unter Lernprogramm: Einrichten Ihrer Postman-Umgebung.

Die allgemeine Struktur einer Antwort mit eingeschlossenen Ressourcen wird im Folgenden gezeigt. Informationen, die sich speziell auf eingeschlossene Ressourcen beziehen, werden fett dargestellt. (Hinweis: JSON unterstützt keine Kommentare. Zur Klarstellung des Codes wurden jedoch Pseudo-Kommentare hinzugefügt. Jedem Pseudo-Kommentar ist ein Hashtag (#) vorangestellt.)

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

Für jede Ressource gibt es einen Abschnitt related, der Folgendes identifiziert:

• Anzahl der eingeschlossenen Ressourcen und
• Die IDs der eingeschlossenen Ressourcen

Das folgende Codefragment stammt beispielsweise aus der Antwort für eine Abfrage aller Aktivitäten und zugehörigen Notizen. Die Aktivität xc:44 enthält eine Notiz mit der ID xc:55.

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

Wenn ein GET den Abfrageparameter included verwendet, aber keine zugehörigen Ressourcen vorhanden sind, wird der Abschnitt related weiterhin angezeigt. Der Zähler ist jedoch 0 und der Datenabschnitt ist leer. Zum Beispiel:

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

Wenn ein GET den Abfrageparameter included auslässt, wird der zugehörige Abschnitt aus den Antwort-Nutzdaten ausgelassen.

Für jede Antwort gibt es einen Abschnitt included, der am Ende der Antwort-Nutzdaten erscheint. Dieser listet Details zu jeder eingeschlossenen Ressource für die primären Ressourcen auf.

Das folgende Codefragment stammt beispielsweise aus dem Abschnitt included des vorherigen Beispiels.

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

Denken Sie daran, dass die Aktivität xc:44 eine Notiz enthält. Die ID der enthaltenen Notiz lautet xc:55. Die im Abschnitt included angezeigte Notiz ist die Notiz, die sich auf die Aktivität xc:44 bezieht.

Für einen bestimmten Endpunkt geben einige der Optionen includeeine Sammlung von Ressourcen für jede primäre Ressource zurück. Andere Optionen include geben für jede primäre Ressource eine einzelne Ressource zurück.

Ein Beispiel für den ersten Fall ist GET /claims/{claimId}?include=contacts. Dieser Aufruf gibt den Schadenfall mit der angegebenen Schadenfall-ID und allen mit diesem Schadenfall verbundenen ClaimContacts zurück. Theoretisch gibt es mehrere zugehörige Ressourcen (ClaimContacts) für jede primäre Ressource (den Schadenfall mit der angegebenen Schadenfall-ID).

Ein Beispiel für den zweiten Fall ist GET /claims/{claimId}?include=mainContact. Dieser Aufruf gibt den Schadenfall mit der angegebenen Schadenfall-ID und dem ClaimContact zurück, der als Hauptkontakt festgelegt ist. Für jede primäre Ressource (den Schadenfall mit der angegebenen Schadenfall-ID) gibt es nur eine einzige zugehörige Ressource (den ClaimContact-Hauptkontakt).

Sie können auch mehrere Optionen "include" angeben, z. B. GET /claims/{claimId}?include=contacts,mainContact. In diesem Fall legt der zugehörige Abschnitt für jeden Schadenfall die ID aller zugehörigen Kontakte fest und identifiziert auch explizit die ID des Hauptkontakts.

Wenn eine Option "include" mit einem Plural benannt wird, gibt sie in der Regel für jede primäre Ressource einen Satz von Ressourcen zurück. Wenn eine Option "include" mit einem Singular benannt wird, gibt sie eine einzelne Ressource für jede primäre Ressource zurück.

Für jeden Endpunkt können Sie die Ressourcen bestimmen, die einbezogen werden können, indem Sie auf das Swagger-UI-Modell für den Endpunkt verweisen. Im Modell befindet sich ein Daten-Envelope, dessen Name mit ...Inclusions endet. Dieser Daten-Envelope listet alle Ressourcen auf, die bei der Abfrage dieses Ressourcentyps einbezogen werden können.

In der gemeinsamen API verweist das Modell für GET /activities beispielsweise auf ein Element ActivityResponseInclusions. Dieses Element hat ein einzelnes untergeordnetes Element - Note. Das bedeutet, dass der einzige Elementtyp, den Sie in eine Aktivitätsabfrage einschließen können, Notizen sind.

Wenn Sie versuchen, einen Ressourcentyp einzuschließen, den ein bestimmter Endpunkt nicht für die Einschließung unterstützt, gibt die API einen Fehlercode 400 und eine Meldung zurück. Der Versuch GET /activities?include=users ergibt beispielsweise die folgende Meldung:

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