API Pattern of the Week: State Transition Operation

Thank you, Olaf Zimmermann, for passing the API Pattern of the Week series baton (see and follow the hashtag #apidpotw for the previous articles). In the previous issue, Olaf looked at how two or more communication participants can exchange data without knowing each other using a Data Transfer Resource; this time, we'll zoom into the State Transition Operation pattern, so let's start with some context information:

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 clients can advance it. For example, functionality in longer-running business processes might require data exchanges, including incremental updates and coordinated application state management to move process instances from initiation to termination stepwise.

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?

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

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.

Figure 1 sketches this solution (PlantUML, from pre-book times):

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 change provider-side state, convey business semantics, and have nontrivial pre- and postconditions and invariants (for instance, "do not deliver the goods and invoice the customer before the customer has checked out and confirmed the order").

Discussion

The resolution of the pattern forces is discussed in the book.

More Information

There 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 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 calling out endpoint roles and operation responsibilities, such as State Transition Operations when preparing and refining candidate endpoint lists.

References

Leymann, Frank, and Dieter Roller. 2000. Production Workflow: Concepts and Techniques. Prentice Hall.

Leymann, Frank, Dieter Roller, and Marc-Thomas Schmidt. 2002. "Web Services and Business Process Management." IBM System Journal 41 (2): 198–211. https://doi.org/10.1147/sj.412.0198.

Bellido, Jesus, Rosa Alarcón, and Cesare Pautasso. 2013. "Control-Flow Patterns for Decentralized RESTful Service Composition." ACM Transactions on the Web (TWEB) 8 (1): 5:1–30. https://doi.org/10.1145/2535911.

Gambi, Alessio, and Cesare Pautasso. 2013. "RESTful Business Process Management in the Cloud." In Proc. 5th ICSE International Workshop on Principles of Engineering Service-Oriented Systems (PESOS), 1–10. https://doi.org/10.1109/PESOS.2013.6635971.

Wirfs-Brock, Rebecca, and Alan McKean. 2002. Object Design: Roles, Responsibilities, and Collaborations. Pearson Education.

The "API Pattern of the Week" series here on LinkedIn featured the following patterns: Wish List, Pagination, Error Report, API Key, Processing Resource, Information Holder Resource, and Data Transfer Resource.

Find the complete pattern description in Chapter 5 of "Patterns for API Design," for instance, at InformIT. There is a 35% discount on the book with code API-PATTERNS.