Custom Actions

The official REST API architecture focuses on the basic create, read, update and delete (CRUD) processes. In complex applications, there is often a need to trigger existing application processes which may produce transient output and so therefore not fit the basic CRUD approach. This is achieved by custom actions, which all use target URLs containing the "custom-actions" path element. Not all actions will require a message body.

For example, all query capabilities use a custom action. See .

The resource query capabilities (seeManage Collections) also use the "custom-actions" URL path element although they do not perform any processes on resources. This is due to one of the following reasons:

• the action is performed with GET.
• the message body is not a resource format.

Resource specific actions are documented in the "Custom Actions" section within the relevant Tasks > Business Objects section. For example, the "Add a shipment to a shipment group by type" action is documented under the Tasks > Business Objects > Shipments > Custom Actions section. This documentation describes the request and response message formats.

Some actions apply to multiple resource types and are either considered to be "global," in the sense that they are available for all resource types, or just "multi-resource," in the sense that they apply to more than one, but not all, resource types.

Multi-resource actions and actions with additional considerations are described in this section.

Note:

Document upload and download actions are an exception to this and are covered in their own section. See Document Content Upload and Download for details.

Common Request Properties

All action request messages will be extensions to the base request which defines the following properties although not all actions will support all properties:

Table - Common Request Properties

Property	Description
responsiblePartyGid	Event reason support
statusCodeGid	Event reason support
reasonCodeGid	Event reason support
pks	Array of PKs to receive action. This is as an alternative to specifying a single PK on the target URL.

Event reason support may not be enabled for all actions and so these properties are optional.

Additional Considerations

Change Service Provider

This action is applicable to the shipments resource and the messages are covered in the Tasks > Business Objects > Shipments > Custom Actions.

This action does not support processing against multiple shipments. If the "pks" array is used in the request message the array MUST have a single element.