Business action POSTs

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

However, in some circumstances, a system API needs to trigger a business process that does not readily map to a single Create, Read, Update, or Delete operation. For example, the system APIs expose 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 ClaimCenter. 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:

  • Endpoints that execute business actions use the POST operation.
  • Endpoints that execute business actions have paths the end in verbs (such as "assign" or "complete").

Examples of endpoints that execute business actions include:

  • POST /common/v1/activities/{activityId}/assign, which assigns the corresponding activity
  • POST /common/v1/activities/{activityId}/complete, which marks the corresponding activity as complete
  • POST /claim/v1/claims/{claimId}/cancel, which cancels the corresponding draft claim
  • POST /claim/v1/claims/{claimId}/submit, which submits the corresponding draft claim, thereby promoting it to an open claim

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 guide.

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 the system APIs, 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.