Pattern Sections
Pattern: State Creation
Operation 
a.k.a. Write-Only Operation, Data Insertion Operation
Context
An API endpoint has been introduced. The API client has expressed its API wants and needs, for instance in the form of user stories and/or given-when-then clauses; non-functional requirements have been elicited as well.
The API client(s) would like to inform the API provider about new client-side incidents without requesting any further server-side processing that would require any immediate response to be returned beyond a simple “got it” acknowledgment (and, provider-internally, initialization of application state).
For instance, the client might want to kick off a long-running business transaction (like an order management and fulfillment process) in the provider or report the completion of a client-side batch job (like the bulk re-initialization of a product catalog). Such creation events cause data to be inserted on the provider side, but this does not become visible to the client.
Problem
How can an API provider allow its clients to report that something has happened that the provider needs to know about, for instance, to trigger instant or later processing?
Forces
The following forces have to be taken into account:
- Coupling trade-offs (accuracy and expressiveness versus information parsimony)
- Timing considerations
- Consistency effects
- Reliability considerations
Pattern forces are explained in depth in the book.
Solution
Add a State Creation Operation
sco: in -> (out,S') that has a write-only nature to the
API endpoint, which may be a
Processing
Resource or an
Information
Holder Resource.
Here ‘writeonly nature’ means that such operations might have to read some state, e.g., to check for duplicate keys in existing data before creation, but their main purpose should be state creation.
The design is sketched in Figure 1.
Sketch
A solution sketch for this pattern from pre-book times is:
Examples
In the online shopping scenario, message such as “new product XYZ created” send from a product management system or “customer has checked out order 123” from an online shop qualify as examples.
Figure 2 gives an example in a fictitious insurance company.
Steps 5 and 6 of the demo “Domain-Driven Service Design with Context Mapper and MDSL” feature an instance of this pattern and introduce the MDSL decorator for it:
"STATE_CREATION_OPERATION" @PaperItemDTO
createPaperItem (String who, String what, String where);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
Known uses of this pattern are common in enterprise information systems and public Web APIs:
- The
submitReportoperation of the Handling Report Service in the Domain-Driven Design Sample Application implementing a cargo tracking scenario allows external clients to notify the application about handling events such as a container arriving at a particular port. - The Slack Event API is a comprehensive implementation of API-based event processing.
- The article “Know the Flow! Microservices and Event Choreographies” by B. Rücker introduces event command transformations and implements an example that includes a usage of this pattern (“order placed”) as well as the sibling pattern State Transition Operation. The articles makes the case for workflow engine usage on the microservice API provider side.
The pattern is often applied in enterprise settings as well (showing how common us of the pattern is):
- Banks can request a new process at the platform Terravis. By calling a “start process” operation, a new process is instantiated and state for it is managed separately from other process instances from now on. Thus, this start operation is a State Creation Operation.
- A provider of a Swiss banking solution software implemented a microservice architecture based on events that are implemented as State Creation Operations. For example, such notifications report modifications of business objects to interested microservices, which in turn can update their local data or initiate processes, e.g., checking a customer against a blacklist.
More Information
Related Patterns
The endpoint-level role patterns Processing Resource and Information Holder Resource may contain instances of this pattern; its sibling patterns (other operation responsibilities) are State Transition Operation (and its variants), Computation Function, and Retrieval Operation (and its variants). A State Transition Operation usually identifies a provider-side state element in its request message (for instance, an order id or serial number of a staff member); State Creation Operations do not have to do this (but might).
Event-Driven Consumer and Service Activator in Hohpe and Woolf (2003) describe how to trigger message consumption asynchronously. Chapter 10 in “Process-Driven SOA” features patterns for integrating events into process-driven SOAs Hentrich and Zdun (2011).
In Domain-Driven Design (DDD), the Domain Event pattern Vernon (2013) has similar semantics and can help to identify State Creation Operations in the variant Event Notification Operation during endpoint identification.
Other Sources
Instances of this pattern may participate in long running and therefore stateful conversations Hohpe (2007).
CQRS and event sourcing are described by Martin Fowler and other authors. As event sourcing and domain events in DDD have gained momentum and popularity in recent years, one can find a lot of best practice advice for modeling and implementing them, for instance in presentations and articles by Vaughn Vernon, and Michael Plöd, and Chris Richardson. Other online resources on event sourcing and CQRS can be found at InfoQ and DZone. The Context Mapper DSL and tools support DDD modeling, model refactoring as well as diagram and service contract generation.
The open source Software/Service/API Design Practice Repository (DPR) features a seven-step service design method to carve out API endpoints and their operations.