Nutzdatenstruktur für eine grundlegende Antwort

Im Folgenden wird die allgemeine Struktur einer Grundantwort dargestellt. Die erste und letzte Eigenschaft (count und Sammlungsebene links) werden nur für Sammlungsnutzdaten verwendet. Alle anderen Eigenschaften werden sowohl für Element- als auch für Sammlungsnutzdaten verwendet.

(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 in collection*
      "data": [                        # List of resources
          {                            # Resource 1 begins here
          "attributes": {              # Resource 1 name/value pairs
              "propertyName": "propertyValue",
              ... },
          "checksum": "val",           # Resource 1 checksum value
          "links": { ... }             # Resource 1 links 
          },                           # Resource 1 ends here
          {                            # Resource 2 begins here
          "attributes": {              # Resource 2 name/value pairs
              "propertyName": "propertyValue",
              ... },
          "checksum": "val",           # Resource 2 checksum value
          "links": { ... }             # Resource 2 links 
          },                           # Resource 2 ends here
      ... ],                           # Resources 3 to N
      "links": { ... }                 # Collection-level links*
}
                                       # *-used only for collection responses

Die Eigenschaft count gibt die Anzahl der Elemente an, die in den Nutzdaten zurückgegeben werden. Sie wird nur in Antworten verwendet, die Sammlungen enthalten.

Der Abschnitt data enthält Informationen über die vom Endpunkt zurückgegebenen Ressourcen. Für jede Ressource werden standardmäßig die folgenden Unterabschnitte angezeigt:

• attributes - Ein Satz von Name/Wert-Paaren für die Felder jeder Ressource.
• checksum - Ein Prüfsummenwert für jede Ressource.
• links - HTTP-Verknüpfungen, die für Aktionen an den einzelnen Ressourcen verwendet werden können.

Wenn ein Endpunkt eine einzelne Ressource zurückgibt, enthält der Datenabschnitt einen einzelnen Satz von attributes, checksum und links. Wenn ein Endpunkt eine Sammlung zurückgibt, enthält der Datenabschnitt für jede Ressource einen Satz von attributes, checksum und links.

Im Unterabschnitt attributes sind die für eine Ressource zurückgegebenen Felder und die Werte für diese Felder aufgeführt. Zum Beispiel:

"attributes": {
    "activityPattern": "check_coverage",
    "activityType": {
        "code": "general",
        "name": "General"
    },
    ...
},

Jede Ressource verfügt über einen Standardsatz von Feldern, die zurückgegeben werden. Dies ist in der Regel eine Teilmenge aller Felder, die zurückgegeben werden können. Sie können den Standardsatz von Feldern überschreiben, die mit dem Abfrageparameter fields zurückgegeben werden. Weitere Informationen finden Sie unter Festlegen, welche Felder über GET abgerufen werden sollen.

"subject": "Verify which coverage is appropriate"

"id": "xc:20",

GET /activities/xc:20/notes

"inlinedResourceName": {
    "inlinedResourceField1": value,
    "inlinedResourceField2": value,
    ...
},

"priority": {
    "code": "urgent",
    "name": "Urgent"
},

"transactionAmount": {
    "amount": "500.00",
    "currency": "usd"

"assignedGroup": {
    "displayName": "Auto1 - TeamA",
    "id": "demo_sample:31"
},
"assignedUser": {
    "displayName": "Andy Applegate",
    "id": "demo_sample:1"
},

Eine checksum ist ein Zeichenfolgenwert, der die "Version" einer bestimmten Ressource angibt. Wenn eine Ressource auf Datenbankebene geändert wird, wird ihr ein neuer Prüfsummenwert zugewiesen. Prozesse, die Daten ändern, können mithilfe von Prüfsummen überprüfen, ob eine Ressource zwischen dem Lesen der Ressource und dem Ändern der Ressource durch einen anderen Prozess nicht geändert wurde.

Weitere Informationen finden Sie unter Verlorene Aktualisierungen und Prüfsummen.

Im Unterabschnitt links des Abschnitts data sind Pfade aufgeführt, die Aktionen angeben, die ggf. für das spezifische Element ausgeführt werden können. Jede Verknüpfung verfügt über einen Namen, eine Eigenschaft href und eine Liste von Methoden. Aufruferanwendungen können diese Links verwenden, um HTTP-Anforderungen für zusätzliche Aktionen zu erstellen, die für diese Ressource ausgeführt werden.

Beispiel: Angenommen, eine aufrufende Anwendung ruft die Aktivität xc:20 ab. Diese Anwendung verfügt über ausreichende Berechtigungen, um diese Aktivität zuzuweisen und die mit dieser Aktivität verbundenen Notizen anzuzeigen. Im Abschnitt "links" für die Aktivität xc:20 erscheint Folgendes:

"links": {
    "assign": {
        "href": "/common/v1/activities/xc:20/assign",
        "methods": [
            "post"
        ]

    },
    "notes": {
        "href": "/common/v1/activities/xc:20/notes",
        "methods": [
            "get",
            "post"
        ]
    },
    "self": {
        "href": "/common/v1/activities/xc:20",
        "methods": [
            "get"
        ]
    }
}

Die Verknüpfung self ist eine Verknüpfung zur Ressource selbst. Die Verknüpfung self ist nützlich, wenn eine aufrufende Anwendung eine Liste von Ressourcen empfängt und zu einer bestimmten Ressource in der Liste navigieren möchte.

Für ein bestimmtes Objekt werden Verknüpfungen, die Geschäftsaktionen ausführen, nur angezeigt, wenn die Aktion angesichts des Status des Objekts sinnvoll ist, und nur, wenn der Aufrufer über ausreichende Berechtigungen zum Ausführen der Aktion verfügt. Beispielsweise wird die Verknüpfung zum Schließen einer Aktivität nicht angezeigt, wenn die Aktivität bereits geschlossen ist. Ebenso wird die Verknüpfung zum Zuweisen einer Aktivität nicht angezeigt, wenn der Aufrufer nicht über die Berechtigung zum Zuweisen von Aktivitäten verfügt.

Wenn eine Antwort eine Sammlung enthält, befindet sich am Ende der Nutzdaten ein Abschnitt links. Dieser Abschnitt ist ein gleichrangiges Element des Abschnitts data. Sie enthält Links, die für die gesamte Sammlung relevant sind, z. B. die Links prev und next, mit denen Sie eine Reihe von Ressourcen durchblättern können.