Payload structure for 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 identifies the number of elements returned in the payload. It is used only in responses that contain collections.

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

"subject": "Verify which coverage is appropriate"

"id": "xc:20",

GET /activities/xc:20/notes

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

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

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

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

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

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.

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.