Standardisierung von Nutzdatenstrukturen

Standardisierung von Informationen, die allen Endpunkten gemein sind

Ein Daten-Envelope ist ein Wrapper, der an die System-APIs gesendetes oder von diesen zurückgegebenes JSON umschließt. Um eine Standard-Nutzdatenstruktur beizubehalten, verwenden die System-APIs zwei Daten-Envelopes: DataEnvelope und DataListEnvelope.

DataEnvelope wird verwendet, um das Informationsformat für ein einzelnes Element zu standardisieren. Es gibt eine Dateneigenschaft mit den folgenden Eigenschaften an: checksum, id, links (für ein einzelnes Element), method, refid, related, type und uri. Auf einer höheren Ebene sieht das Format der Nutzdaten für ein einzelnes Element wie folgt aus:

{
    "data": {
        "checksum": ...,
        "id":       ...,
        "links":    ...,
        "method":   ...,
        "refid":    ...,
        "related":  ...,
        "type":     ...,
        "uri":      ...
        }
    }
}

DataListEnvelope wird verwendet, um das Format von Informationen für Sammlungen zu standardisieren. Es gibt die folgenden Eigenschaften an, die gleichrangig mit dem Datenabschnitt sind: count, links (für eine Sammlung), und total. Auf einer höheren Ebene sieht das Format der Nutzdaten für ein einzelnes Element wie folgt aus:

{
    "count"    ...,
    "data": [
        { properties_for_element_1 },
        { properties_for_element_2 },
        ...
    ],
    "links":   ...,
    "total":   ...
}

Nicht jede Eigenschaft wird in allen Nutzdaten angezeigt. Es gibt verschiedene Gründe, warum eine Eigenschaft nicht in bestimmten Nutzdaten angezeigt wird. Zum Beispiel:

• Einige Eigenschaften, z. B. refid, gelten nur für Anforderungen und werden nicht in Antwort-Nutzdaten angezeigt.
• Einige Eigenschaften, z. B. count, gelten nur für Antworten und werden nicht in Anforderungs-Nutzdaten angezeigt.
• Einige Eigenschaften, z. B. related, werden standardmäßig nicht und nur dann angezeigt, wenn die Anforderung bestimmte Abfrageparameter enthält.

Standardisierung von spezifischen Informationen für einen bestimmten Endpunkt

DataEnvelope und DataListEnvelope stellen ein Standardformat für Informationen bereit, das für alle Anforderungs- und Antwort-Nutzdaten gilt. Verschiedene Endpunkte interagieren jedoch mit verschiedenen Ressourcentypen. Für jeden Endpunkt muss ein Abschnitt der Nutzdaten Informationen über einen bestimmten Ressourcentyp bereitstellen.

Um dies zu erreichen, verwenden die System-APIs auch Anforderungs- und Antwortschemas. Ein Anforderungsschema ist ein Schema, das verwendet wird, um die gültige Struktur von Anforderungs-Nutzdaten für einen bestimmten Satz von Endpunkten zu definieren. Analog dazu ist ein Antwortschema ein Schema, das verwendet wird, um die gültige Struktur von Antwort-Nutzdaten für einen bestimmten Satz von Endpunkten zu definieren.

Anforderungs- und Antwortschemas sind hierarchisch. Für Antworten verwendet beispielsweise der GET /activity/{activityId}-Endpunkt das ActivityResponse-Schema. Dieses Schema hat zwei untergeordnete Schemas: ActivityData und ActivityResponseInclusions.

Anforderungs- und Antwortschemas erweitern DataEnvelope oder DataListEnvelope. Dadurch wird sichergestellt, dass Informationen, die für alle Endpunkte relevant sind, standardmäßig in Nutzdaten angezeigt werden.

Anforderungs- und Antwortschemas definieren auch eine attributes-Eigenschaft für die Nutzdaten. Diese Eigenschaft ist mit einem Schema verknüpft, das ressourcenspezifische Informationen für die Nutzdaten enthält. Beispiel: Der Endpunkt GET /activity/{activityId} gibt eine attributes-Eigenschaft im untergeordneten ActivityData-Schema an. Diese Eigenschaft ist mit dem Activity-Schema verknüpft, das aktivitätsspezifische Felder enthält, z. B. activityPattern und activityType. Daher haben Antwort-Nutzdaten für den Endpunkt GET /activity/{activityId} die folgende Struktur:

{
    "data": {
        "checksum": ...,
        "attributes" : {
            "activityPattern": ... ,
            "activityType": ...,
            ...},
        "id":       ...,
        "links":    ...,
        "method":   ...,
        "refid":    ...,
        "related":  ...,
        "type":     ...,
        "uri":      ...
        }
    }
}