Standardizing payload structures

Communication between caller applications and Cloud API is easier to manage when the information in the payloads follows a standard structure. Cloud API has standard structures for both request payloads and response payloads. The structures are defined by data envelopes, and by request and response schemas.

Standardizing information common to all endpoints

A data envelope is a wrapper that wraps JSON sent to or returned from Cloud API. To maintain a standard payload structure, Cloud API uses 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 properties: checksum, id, links (for a single element), method, refid, related, type and uri. At a high level, the format of a payload for a single element looks like:

{
    "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: count, links (for a collection), and total. At a high level, the format of a payload for a single element 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, Cloud API also uses 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":      ...
        }
    }
}

Viewing request schemas

You can use Swagger UI to review the structure of a request payload for a given endpoint. This includes the hierarchy of schemas and the type of information in each schema. The information appears in the description of the endpoint's body parameter on the Model tabs.

View a request schema in Swagger UI

Procedure

  1. Start PolicyCenter.
  2. In a web browser, navigate to the Swagger UI for the appropriate API.
  3. Click the method button for the appropriate endpoint. Swagger UI shows details about that endpoint underneath the endpoint name.
    • For example, to view the request schema for POST /activities/{activityID}/notes, click the POST button for that endpoint.
  4. Scroll down to the Body entry in the Parameters section. The Model tab shows the hierarchy of data envelopes for this endpoint, and the contents of each data envelope.