Resource Sets

Resource sets are resources with a matching state property. Resource sets cannot be accessed via a URI as they are abstract grouping of resources.

If you think of resources like a database, a resource set functions like the result of a search query, unlike a resource collection which functions like looking at a data table.

Changing the state property of a resource differs from updating other properties because business rules are enforced when a state is updated. For example, in the Transfers API, you can not cancel a scheduled transfer which is currently being processed by the bank, nor can you resume a transfer which is not suspended.

To enforce these types of business rules, state transitions are executed with operations that place a resource into a resource set. The resource set represents a set of all resources that are in a specific state.

The state property is immutable via PATCH or PUT, which are used for most updates to a resource. To change the state of a resource, use an API operation that performs an action on the resource. For example, payment batch actions include submitting batch, approving batch, and rejecting batch. These actions change the state of the payment batch, while also performing other business logic.

The APIs use POST to perform the operation of placing a resource into a resource set. For example, submitting a valid payment batch could change the batch’s state from pending to pendingApproval. These actions add the batch to the resource set of pending approval batches.