An action resource represents an executable process rather than a persistent business entity. Use POST when a non-CRUD operation needs input, processing, and a result; HTTP does not restrict resources to business concepts. section 4.7.1 section 4.8.3
Checking out a cart
Represent checkout with POST /check-out, or POST /carts/{cartId}/check-out when multiple carts exist. With no input, the operation can return 201 Created, the created order in the body, and Location: /orders/123456. A volatile operation can use POST /sum with two numbers in the body and return 200 OK with their sum. section 4.7.1
Choose an action-resource design after identifying the operation’s purpose:
- Use an action resource such as POST /accounts/{accountId}/close when the capability deserves a distinct operation. section 9.9.2
- Prefer a noun-based business concept such as POST /checkouts or POST /account-closures when the operation needs retrieval, search, long-running processing, or additional features. section 4.7.2 section 4.9
- Model the action body as function-like input and return input plus output when consumers need to understand the result’s source. section 5.4.3
Figure 4.18 To represent a “do” action, we can create an action resource, turn the action into a business concept, or focus on the action’s result.
Compare three representations for a non-CRUD operation: an action resource, a nominalized business concept, and a resource based on the action’s result. section 4.7
