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.

The resource query capabilities (see Manage 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 "Actions" section within the relevant Tasks > Actions > Business Actions > Business Objects section. For example, the "Add a shipment to a shipment group by type" action is documented in the Tasks > Actions > Business Actions > Shipments section. This documentation describes the request and response message formats.

Some actions apply to multiple resource types and are either considered to be "utility," in the sense that they're 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 listed under Tasks > Actions > Utility Actions.

You can process custom actions both synchronously and asynchronously. See the Asynchronous Processing section for details if you want to process them asynchronously.

Note:

Not all custom actions can be run asynchronously; only some actions have been enabled for asynchronous processing. Currently these are available:
  • /logisticsRestApi/resources-int/v2/custom-actions/riqRateAndRoute
  • /logisticsRestApi/resources-int/v2/custom-actions/riqNetworkRateAndRoute

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.