Standard payload structures

The endpoints in Cloud API have standard structures for both request payloads and response payloads. The structures are defined by data envelopes, and by request and response schemas.

Standard information common to all endpoints

A data envelope is a wrapper that wraps JSON sent to or returned from a REST API. To maintain a standard payload structure, Cloud API uses two data envelopes: DataEnvelope and DataListEnvelope.

DataEnvelope standardizes the format of information for a single element. It specifies a data property with the following child properties:

  • checksum
  • id
  • links (for a single element)
  • method
  • refid
  • related
  • type
  • uri
The format of a payload for a single element has the following structure:
{
    "data": {
        "checksum": ...,
        "id":       ...,
        "links":    ...,
        "method":   ...,
        "refid":    ...,
        "related":  ...,
        "type":     ...,
        "uri":      ...
        }
    }
}

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

  • count
  • links (for a collection)
  • total

The format of a payload for a collection has the following structure:

{
    "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.

Standard 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 schemas

You can use API definition tools, such as Swagger UI, to review information about the schemas for a given endpoint and how they structure the data.

View a response 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 operation button for the appropriate endpoint. Swagger UI shows details about that endpoint underneath the endpoint name.
    • For example, to view the response schema for GET /activities/{activityID}, click the GET button for that endpoint.
  4. Scroll down to the Responses section. The Model tab shows the hierarchy of schemas for this endpoint, and the contents defined by each schema.