Pattern Sections
Pattern: State
Transition Operation 
a.k.a. Read-Write Operation, Data Change Operation, Business Activity Processor
Context
It has been decided to expose business functionality in an API. The functionality should be decomposed into multiple activities, whose execution state should be visible in the API so that clients can advance it. For example, functionality that is part of longer-running business processes might require data exchanges including incremental updates and coordinated application state management to move process instances from initiation to termination in a stepwise fashion.
The business process behavior and interaction dynamics might have been specified in a use case model and/or set of related user stories, or even an analysis-level business process model (using BPMN, UML activity diagrams or an equivalent notation).
Problem
How can a client initiate a processing action that causes the provider-side application state to change?
How can API clients and API providers share the responsibilities required to execute and control business processes and their activities? More specifically:
- How can API clients ask an API provider to take over certain functions that represent business activities of varying granularities, from atomic activities to subprocesses to entire processes, but still own the process state (“Frontend BPM”)?
- How can API clients initiate, control and follow the asynchronous execution of remote business processes (including subprocesses and activities) exposed and owned by an API provider (“Business Process Management (BPM) services”)?
A canonical example process from the insurance domain is claim processing, with activities such as initial validation of a received claim form, fraud check, additional customer correspondence, decision, payment/settlement, and archiving. Instances of this process can live for days to months or even years. Process instance state has to be managed; some parts of the processing can run in parallel whereas others have to be executed one by one sequentially. When dealing with such complex domain semantics, the control and data flow depends on a number of decisions. Multiple systems and services might be involved along the way, each exposing one or more APIs. Other services and application frontends act as API clients. The process instances and the state ownership can lie with the API client (Frontend BPM), with the API provider (BPM services), or be shared.
Forces
The following specific forces have to be resolved when representing business processes and their activities as API operations, or, more generally speaking, updating provider-side application state:
- Service granularity
- Consistency and auditability
- Dependencies on state changes being made beforehand, which may collide with other state changes (e.g., transactions).
- Workload management
- Networking efficiency versus data parsimony (message sizes)
Time management and reliability also qualify as forces of this pattern; these design concerns are discussed in the pattern State Creation Operation.
Pattern forces are explained in depth in the book.
Solution
Introduce an operation in an API endpoint that combines client input
and current state to trigger a provider-side state change
sto: (in,S) -> (out,S'). Model the valid state
transitions within the endpoint, which may be a
Processing
Resource or an
Information
Holder Resource, and check the validity of incoming change requests
and business activity requests at runtime.
Pair a Command Message with a Document Message (two “Enterprise Integration Patterns” Hohpe and Woolf (2003)) to describe the input and the desired action and receive an acknowledgment or result.
Sketch
A solution sketch for this pattern from pre-book times is:
Example
The activity “proceed to checkout and pay” in an online shop illustrates the pattern in an order management process. “Add item to shopping basket” then is an activity in the “product catalog browsing” subprocess. These operations do change provider-side state, they do convey business semantics, and they do have nontrivial pre- and postconditions as well as invariants (for instance, “do not deliver the goods and invoice the customer before the customer has checked out and confirmed the order”).
The following example from the insurance domain illustrates the two extremes of the pattern; see Figure 4. Offers are created in a single-step operation; claims are managed step-by-step, causing incremental state transitions on the provider side. Some of the primitives from Figure 3 are assigned to State Transition Operations in the example.
Are you missing implementation hints? Our papers publications provide them (for selected patterns).
Consequences
The resolution of pattern forces and other consequences are discussed in our book.
Known Uses
The Application
Layer of the Domain-Driven
Design Sample Application implements (local) interfaces for two
instances of this pattern: BookingService.java and
CargoInspectionService.java.
PayPal has the notion of controller resources and M. Nygard also recommends this behavior- and reponsibility-oriented pattern when talking about activity sets and process services. Note that Nygard considers entity services an anti pattern in all cases, unlike other authors who argue that context matters.
Advocates of workflow engines recommend lightweight microservice compositions as well, for instance to decouple steps with an event command transformation.
A large body of State Transfer Operations can be found in enterprise settings (just to show how common the pattern is):
- Most of the 1000+ services in the core banking SOA featured in Brandner et al. (2004) qualify as known uses of this pattern, for instance, money transfers.
- The same holds for the business and application services in the telecommunications order management SOA presented in Zimmermann et al. (2005); for instance, the scheduling of a technician visit when customers relocate or upgrade their telephony services is part of a medium complex business process (or workflow).
- The Swiss land register Terravis uses State Transition Operations in its backend infrastructure, e.g., for managing mortgages in a position keeping service (e.g., transfer mortgage from one depot to another) or for moving forward in a business process instance (e.g., submit digitally signed document) Lübke and Lessen (2016).
More Information
Related Patterns
The patterns differs from its siblings like this: A Computation Function does not touch the provider side application state (read or write) at all; a State Creation Operations only writes to it (in append mode). Instances of Retrieval Operation read, but do not write it; State Transition Operation instances both read and write the provider-side state. Computation Function and Retrieval Operation pull information from the provider; State Creation Operations (such as instances of its Event Notification Operation variant) push updates to the provider. State Transition Operations may push and/or pull. A State Transition Operation may refer to a provider-side state element in its request message (for instance, an order id or serial number of a staff member); State Creation Operations usually do not do this. A single API endpoint may, but not necessarily should apply more than one of these patterns; command-query separation is a principle from object-oriented programming also eligible on the architectural level.
State Transition Operations can be seen to trigger and/or realize the Business Transactions Fowler (2002). Instances of this pattern may participate in long running and therefore stateful conversations Hohpe (2007). They can use and go along with one or more of the RESTful conversation patterns from Pautasso, Ivanchikj, and Schreier (2016). For instance, one may want to consider factoring out the state management and the computation part of the pattern into separate services. Conversation patterns or choreographies and/or orchestrations may then define the valid combinations and execution sequences of these services.
State Transition Operations are often exposed in Community APIs; if this is done, they can be protected with an API Key and their usage can be governed with a Service Level Agreement.
In Domain-Driven Design (DDD) Evans (2003), the Aggregate and Entity patterns have related semantics (i.e., they represent groups of domain concepts that have an identify and a lifecyle). Hence, these patterns can help to identify State Transition Operation candidates during endpoint identification. It is important not to expose the entire domain as Published Language on the API level because this creates an undesired tight coupling between the API clients and the provider-side API implementation.
Other Sources
The is a large body of literature on BPM(N) and workflow management that introduces concepts and technologies to implement stateful service components in general and State Transition Operations in particular, for instance Leymann and Roller (2000), Leymann, Roller, and Schmidt (2002), Bellido, Alarcón, and Pautasso (2013), Gambi and Pautasso (2013).
In Responsibility-Driven Design (RDD), State Transition Operations correspond to coordinators and controllers that are encapsulated as service providers made accessible from remote with the help of an interfacer as described in Wirfs-Brock and McKean (2002).
The seven-step service design method in the Software/Service/API Design Practice Repository (DPR) suggests to call out endpoint roles and operation responsibilities such as State Transition Operation when preparing candidate endpoint lists and refining them.