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 include any included resources. Included resources are discussed in Payload structure for a response with included resources.
Examples of response payloads in Postman
You can use the following Postman calls to load examples of response payloads. All of these calls assume the following:
- Your instance of ClaimCenter is installed on your local machine.
- The Demo sample data has been loaded.
- The call uses basic authentication with user
aapplegate
and passwordgw
.
Response payload examples
Response payload for a single resource:
- Activity "Contact claimant" (whose Public ID is cc:20)
- GET
http://localhost:8080/cc/rest/common/v1/activities/cc:20
- GET
- Claim 235-53-365870 (whose Public ID is demo_sample:1)
- GET
http://localhost:8080/cc/rest/claim/v1/claims/demo_sample:1
- GET
Response payload for a collection:
- All activities assigned to Andy Applegate
- GET
http://localhost:8080/cc/rest/common/v1/activities
- GET
- All claims assigned to Andy Applegate
- GET
http://localhost:8080/cc/rest/claim/v1/claims
- GET
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 resource, 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 Specifying which fields to GET.
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 ClaimCenter. 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",
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 Specifying which fields to GET.
Broadly speaking, there are four types of inlined resources: typelists, monetary 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"
},
Monetary amount values are complex values with a currency field and an amount field. For example:
"transactionAmount": {
"amount": "500.00",
"currency": "usd"
(Note that in the system APIs, the datatype is referred to as
MonetaryAmount
. But in ClaimCenter, these values are actually stored
using the CurrencyAmount
datatype.)
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 paths that 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.
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.
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.