Standardizing payload structures

Standardizing information common to all endpoints

A data envelope is a wrapper that wraps JSON sent to or returned from the system APIs. To maintain a standard payload structure, the system APIs use two data envelopes: DataEnvelope and DataListEnvelope.

DataEnvelope is used to standardize the format of information for a single element. It specifies a data property with the following child properties:

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

DataListEnvelope is used to standardize the format of information for collections. It specifies the following properties, which are siblings to the data section:

The format of a payload for a collection looks like:

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

Every property does not appear in every payload. There are different reasons why a property may not appear in a given payload. For example:

• Some properties, such as refid, apply only to requests and do not appear in response payloads.
• Some properties, such as count, apply only to responses and do not appear in request payloads.
• Some properties, such as related, do not appear by default and appear only when the request includes certain query parameters.

Standardizing information specific to a given endpoint

DataEnvelope and DataListEnvelope provide a standard format for information that is applicable to all request and response payloads. But, different endpoints interact with different types of resources. For each endpoint, some portion of the payload must provide information about a specific type of resource.

To address this, the system APIs also use request schemas and response schemas. A request schema is a schema that is used to define the valid structure of a request payload for a specific set of endpoints. Similarly, a response schema is a schema that is used to define the valid structure of a response payload for a specific set of endpoints.

Request and response schemas are hierarchical. For example, for responses, the GET /activity/{activityId} endpoint uses the ActivityResponse schema. This schema has two child schemas: ActivityData and ActivityResponseInclusions.

Request and response schemas extend DataEnvelope or DataListEnvelope. This ensures that information relevant to all endpoints appears in payloads in a standard way.

Request and response schemas also define an attributes property for the payload. This property is associated with a schema that includes resource-specific information for the payload. For example, the GET /activity/{activityId} endpoint specifies an attributes property in the ActivityData child schema. This property is associated with the Activity schema, which contains activity-specific fields, such as activityPattern and activityType. As a result, response payloads for the GET /activity/{activityId} endpoint have this structure:

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