Designing a request payload
Determining the required, optional, and write-only fields
Within the context of a request payload, each field of a given resource is either:
- Required - This field must be included.
- Optional - This field can be included or omitted.
- Read-only - This field cannot be included.
Required fields
A required field must be included in the request payload. A field can be required for one of several reasons:
- The field is marked as required on the associated schema, and therefore must be included on all POSTs using that schema.
- The field is not marked as required on the associated schema, but it is always required by PolicyCenter. (For example, the underlying database column could be marked as non-nullable with no default and the application does not generate a value for it.)
- The field is not required by the API, but it is sometimes required by PolicyCenter. (For example, there could be a validation rule in PolicyCenter that says non-confidential documents do not require an author, but confidential documents do. Therefore, the author field is required only some of the time.)
Whether a field is required or allowed in a POST does not always match the requiredness of the corresponding data model entity or database column. For example:
- A field may be marked as non-nullable in the database (and therefore "required"). But, PolicyCenter always generates a value for it. Therefore, the field is marked as read-only and not required in the API schema.
- A field may be marked as non-nullable in the database (and therefore "required") and required when an object is created. But once the object is created, the value of the field cannot be changed. Therefore, the field is required for creation, but read-only for updates.
Determining that a field is required by the API
If a field is required by the API, the schema specifies the following property for the field:
"requiredForCreate": true
For example, the Claim API has a POST claim/{claimId}/contacts
endpoint
that creates a contact for a given claim. One of the data envelopes used by this endpoint to
define the request schema is the ClaimContact
schema. It contains the
following:
contactSubtype string
x-gw-type: typekey.Contact
x-gw-extensions: OrderedMap { "createOnly": true,
"requiredForCreate": true }
dateOfBirth string($date)
x-gw-nullable: true
x-gw-extensions: OrderedMap { "before": "now",
"entitySubtype": "Person" }
Note that the contactSubtype
field has the "requiredForCreate":
true
property, whereas the dateOfBirth
field does not. This
means that the API requires a contact subtype for contact creation, but not a date of
birth.
Determining that a field is required by the application
If a field is not required by the API but is required by the application, the only way to
identify this is to send a request to the application. If there is a required value that is
missing from the request payload, you will get a BadInputException
response
with a message identifying the missing fields. For example:
{
"status": 400,
"errorCode": "gw.api.rest.exceptions.BadInputException",
"userMessage": "The 'body' field is required when creating notes"
}
Read-only fields
Read-only fields are fields that are set within the application (either by a user or by
application logic) and cannot be set or modified by system API calls. Read-only fields are
listed in the request schema as readonly: true
. You can view this
information in Swagger UI from the endpoint's Model tab.
For example, this is the Model text for the POST
/activity/{activityId}/notes
endpoint's createDate
field:
createdDate string($date-time)
readOnly: true
You cannot include read-only values in a request payload. If you do, the API returns a
BadInputException
with an error message such as:
"message": "Property 'createdDate' is defined as read-only and cannot be specified on inputs"
Optional fields
From a technical perspective, any field that is neither required nor read-only is optional. These fields can be either include or omitted as appropriate.
Request payload structure
The basic structure for a request payload that creates a single resource is:
{
"data":
{
"attributes": {
<field/value pairs are specified here>
}
}
}
For example, this request payload could be used to create a note:
{
"data":
{
"attributes": {
"subject": "Main contact vacation",
"body": "Rodney is on vacation for the entire month of June.
During this time, direct any questions to Sarah Jackson.",
"confidential": false,
"topic": {
"code": "general"
}
}
}
}
In some situations, you can create an object using an "empty body" (a body that specifies
no values). An object created in this way will contain only default values. In these
situations, the payload has an empty attributes
section:
{
"data":
{
"attributes": {
}
}
}
Specifying scalar values in a request payload
Formats for values are the same for request payloads and response payloads. For a given field, you can use its format in a response payload as a model for how to build a request payload.
On a schema, field value types for scalar values are marked using the type
property. In request payloads, scalar values follow these patterns:
Field value type | Pattern | Example | Notes |
---|---|---|---|
String | "fieldName" : "value" |
|
IDs are considered strings. |
Integer | "fieldName" : value |
"numDaysInRatedTerm": 180 |
Unlike the other scalar value types, integer, Boolean, and null values are expressed without quotation marks. |
Decimal | "fieldName" : "value" |
"speed": "60.0" |
|
Date | "fieldName" : "value" |
"dateReported": "2020-04-09" |
Expressed using the format YYYY-MM-DD |
Datetime | "fieldName" : "value" |
"createdDate": "2020-04-09T18:24:57.256Z" |
Expressed using the format YYYY-MM-DDT hh:mm:ss.fffZ where T and Z are literal values. |
Boolean | "fieldName" : value |
"confidential": false |
Unlike the other scalar value types, integer, Boolean, and null values are expressed without quotation marks. |
IDs
ID values are assigned by PolicyCenter. Therefore, you cannot specify an ID for an object that is being created. However, you can specify IDs when identifying an existing object that the new object is related to.
Specifying objects in a request payload
The syntax for specifying an object is:
"objectName": {
"field1": value_or_"value",
"field2": value_or_"value",
...
}
For example:
"assignedUser": {
"displayName": "Andy Applegate",
"isActive": true
}
The value of each object's field either uses or does not use quotation marks based on the
datatype of the field. (For example, assignedUser
has a
displayName
field. The value for this field is a string, so the value is
specified in quotes. If assignedUser
also had an isActive
field, which was a Boolean, the value would be specified as either true
or
false
without quotes.
Typekeys and money values are expressed in objects. Each of these are specified using a standard pattern.
Typekeys
Typekeys use the following format:
"field": {
"code": "value"
}
For example:
"priority": {
"code": "urgent"
}
Typekeys also have a name
field, which is included in responses. But, the
name field is not required. If you include it in a request schema, it is ignored.
Monetary amounts
Monetary amounts use the following format:
"field": {
"amount": "amountValue",
"currency": "currencyCode"
}
For example:
"transactionAmount": {
"amount": "500.00",
"currency": "usd"
}
Related objects
For information on how to specify related objects in a request payload, see Request inclusion.
Setting values and objects to null
To set the value of a field to null, use the following syntax:
Field value type | Pattern | Example | Notes |
---|---|---|---|
Field whose value is to be set to null | "fieldName" : null |
"middleName": null |
You can set any scalar value to null. Express it without quotation marks. |
To set the value of an object to null, specify the null at the object field level. For example, a user can optionally have a home phone number. The following explicitly states that the home phone number is null:
"homePhone": null
To set a typekey to null, specify the null at the typekey field level. (Do not specify
the null at the code level.) For example, the following sets a document's
language
field to null:
"language": null
To set a monetary amount or currency amount to null, specify the null at the field level.
(Do not specify the null at the amount and currency level.) For example, the following
sets a transactionAmount
field to null:
"transactionAmount": null