Business action POSTs

True REST APIs focus exclusively on the CRUD methods (Create, Read, Update, Delete). Like other REST APIs, Cloud API exposes these CRUD methods through endpoints that support the POST, GET, PATCH, and DELETE methods.

However, in some circumstances, Cloud API needs to trigger a business process that does not readily map to a single Create, Read, Update, or Delete operation. For example, Cloud API exposes the ability to assign an activity. This action modifies the value of the activity's assignedUser and assignedGroup fields. But, the assigned user and group can be determined by assignment logic internal to PolicyCenter. Assignment could vary based on the activity itself, on the current workload of each group, or on whether a given user is on vacation or not. Activity assignment cannot be executed through a PATCH because the caller application cannot always determine how to set the assignedUser and assignedGroup fields.

In standard REST architecture, there is no operation for this type of business action. Therefore, Cloud API has adopted the following conventions:

Examples of endpoints that execute business actions include:

Business action POSTs and request payloads

All POST endpoints that create resources (such as POST /common/v1/activities/{activityId}/notes, which creates a note for the given activity) require a request payload. For some endpoints, the payload can be empty. But, a request payload is always required.

For POST endpoints that execute business actions, payload requirements can vary.

• Some business action POSTs require a payload. (For example, activities/{activityId}/assign requires a payload that specifies the assignment criteria.)
• Some business action POSTs can optionally have a payload. (For example, activities/{activityId}/complete does not require a payload. But you can specify one if you want to attach a note to the activity while you complete it.)
• Some business action POSTs may not permit any payload.

To determine whether a business action POST requires, allows, or forbids a request payload, refer to the relevant section of this documentation.

Business action POSTs and lost updates

When a business process spans multiple calls, the first call is typically either a GET that retrieves data, or a POST that creates data. If the business process involves a POST that executes a business action, this POST typically comes after the first call, and it typically acts on a resource that was queried for or created in a previous call.

It is possible for some other process to modify the data after the initial GET/POST, but before the subsequent business action POST. This can cause a lost update. Within Cloud API, a lost update is a modification made to a resource that unintentionally overwrites changes made by some other process.

You can prevent lost updates using checksums. For more information, see Lost updates and checksums.