Payload structure for a basic response

The following sections describe the response payload for a basic response. For the purpose of this discussion, a basic response is a response that contains information about a specific element or collection, but does not contain any included resources. Included resources are discussed in Payload structure for a response with included resources.

Structure of a basic response

The high-level structure of a basic response is shown below. The first and last properties (count and collection-level links) are used only for collection payloads. All other properties are used for both element and collection payloads.

(Note: JSON does not support comments. However, to clarify the code, pseudo-comments have been added. Each pseudo-comment is preceded by a hashtag (#).)

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

The count property

The count property identifies the number of elements returned in the payload. It is used only in responses that contain collections.

The data section

The data section contains information about the resources returned by the endpoint. For each resource, the following subsections appear by default:

  • attributes - A set of name/value pairs for the fields of each resource.
  • checksum - A checksum value for each resource.
  • links - HTTP links that can be used to take action on each resource.

If an endpoint returns a single element, the data section has a single set of attributes, checksum, and links. If an endpoint returns a collection, the data section has one set of attributes, checksum, and links for each resource.

The attributes section

The attributes subsection lists the fields returned for a resource, and the values for those fields. For example:

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

Each resource has a default set of fields that are returned. This is typically a subset of all the fields that could be returned. You can override the default set of fields returned using the fields query parameter. For more information, see The fields query parameter.

Simple values

When a field is a scalar, its value is listed after the colon. For example:

"subject": "Verify which coverage is appropriate"

ID properties

Every resource has an id field. This has the same value as the Public ID of the object in PolicyCenter. This is typically one of the fields returned by default. For example:

"id": "xc:20",

This value is also used in an endpoint that names a specific element, such as:

GET /activities/xc:20/notes

Date and datetime values

Date and datetime values appear in payloads as a string with the following format:
  • Datetime: YYYY-MM-DDThh:mm:ss.fffZ
  • Date: YYYY-MM-DD

where:

  • YYYY is the year
  • MM is the month
  • DD is the day
  • For datetime values:
    • T is a literal value that separates the date portion and the time portion
    • hh is the hour
    • mm is the minute
    • ss is the second
    • fff is the second fraction
    • Z is a literal value that means "zero hour offset". It is also known as "Zulu time" (UTC)

For example:

"dueDate": "2020-03-23T07:00:00.000Z",

Be aware that, for some fields, Cloud API requires a date value as an input. But, PolicyCenter stores the value as a datetime value, and therefore the value in response payloads is a datetime value. This behavior is an attempt to closely model the PolicyCenter behavior of adding a time value to entered date values. For example, the JobEffectiveDate field is specified in the CreateSubmissionAttributes schema as a date value. But once the submission has been created, the JobEffectiveDate field in the response payload will have a datetime value.

Inlined resources

Some response payloads contain inlined resources. An inlined resource is a resource that is not the root resource, but some of its fields are listed in the attributes section by default along with fields from the root resource. Inlined resources follow the format:

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

Inlined resources are declared in the response schema. Similar to scalar values, you can control which inlined resources and inlined resource fields are returned in a response by using the fields query parameter. For more information, see The fields query parameter.

Broadly speaking, there are four types of inlined resources: typelists, currency amount values, simple references, and complex references.

Typelists are listed with a code field and a name field. They use the TypeCodeReferences schema. For example:

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

Currency amount values have a currency field and an amount field. For example: 

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

Simple references are references to a related object that use the SimpleReferences schema. This schema includes only the following fields: displayName, id, refId, type, and uri. By default, most endpoints return only displayName and id.

For example, in the following snippet, assignedGroup and assignedUser are simple references:

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

Complex references are references to a related object that uses a schema more complex than the SimpleReferences schema. For example, when a contact's primary address is added to a response payload, it uses the Address schema, which includes a larger number of fields.

Fields with null values are omitted

Response payloads contain only fields whose values are non-NULL. Fields with NULL values are omitted from the response payload.

If a given field is expected in a response payload but it is missing, this is often because the value was NULL.

The checksum field

The checksum field lists a value that identifies the "version" of a resource. Whenever a resource is modified at the database level, it is assigned a new checksum value. Processes that modify data can use checksums to verify that a resource has not been modified by some other process in between the time the resource was read and the time the resource is to be modified.

For more information, see Lost updates and checksums.

The links subsection (for an element)

The links subsection of the data section lists a set of paths which identify actions that can be taken on the specific element, if any. Each link has a name, an href property, and a list of methods. Caller applications can use these links to construct HTTP requests for additional actions to take on that resource.

Note: The links subsection of the data section is one of the way in which Cloud API enforces the Hypermedia as the Engine of Application State (HATEOAS) constraint.

For example, suppose that a given caller application gets activity xc:20. This application has sufficient permission to assign this activity and to view the notes associated with this activity. The following would appear in the links section for activity xc:20: 

"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"
        ]
    }
}

The self link is a link to the resource itself. The self link is useful when a caller application receives a list of resources and wants to navigate to a specific resource in the list.

For a given object, links that execute business actions appear only if the action makes sense given the state of the object, and only if the caller has sufficient permission to execute the action. For example, the link to close an activity will not appear if the activity is already closed. Similarly, the link to assign an activity will not appear if the caller lacks permission to assign activities.

The collection-level links section

If a response contains a collection, there is a links section at the end of the payload. This section is a sibling of the data section. It contains links that are relevant to the entire collection, such as the prev and next links that let you page through a large set of resources.

Note: The links section at the end of a collection-level payload is one of the way in which Cloud API enforces the Hypermedia as the Engine of Application State (HATEOAS) constraint.