Pattern Sections
Pattern: Processing
Resource 
a.k.a. Command Service, Controller Resource, Executor, Processing Endpoint
Context
The functional requirements for an application have been specified, e.g., in the form of agile user stories and/or analysis-level business process models. An analysis of the functional requirements suggests that one or more remote capabilities should be invoked; Frontend Integration and/or Backend Integration are required and application domain-driven APIs and their clients have to be designed. A (micro-)services architecture and integration infrastructure have been defined initially.
Problem
How can an API provider allow its clients to trigger an action in it?
Such actions may be standalone commands (application domain-specific ones or technical utilities) or activities in a business process; they may or may not read and write provider-side application state. A suitable level of abstraction is desired that only exposes the action and hides data as much as possible.
Forces
When invoking provider-side processing upon request from remote clients, general design concerns are:
- Contract expressiveness and service granularity (and their impact on coupling)
- Learnability and manageability
- Semantic interoperability
- Response time
- Security and privacy
- Compatibility and evolvability
These forces conflict with each other partially. For instance, the more expressive a contract is, the more has to be learned, managed, and tested (w.r.t. interoperability). Finer-grained services might be easier to protect and evolve, but there will be many of them, which have to be integrated Neri et al. (2020).
A key decision is whether the endpoint should have activity- or data-oriented semantics. This pattern explains how to emphasize activity; its Information Holder Resource sibling focuses on data orientation.
Pattern forces are explained in depth in the book.
Solution
Add a Processing Resource endpoint to the API exposing operations that bundle and wrap application-level activities or commands.
Sketch
A solution sketch for this pattern from pre-book times is:
Example
The Policy
Management Backend of the Lakeside Mutual microservices sample
contains a stateful Processing
Resource InsuranceQuoteRequestProcessingResource that
offers
State
Transition Operations which move an insurance quotation request
through various stages. The resource is implemented as an HTTP resource
API in Java and Spring Boot. It also contains
RiskComputationService, a stateless
Processing Resource that implements
a single
Computation
Function called computeRiskFactor:
@RestController
@RequestMapping("/riskfactor")
public class RiskComputationService {
@ApiOperation(
value = "Computes the risk factor of a customer.")
@PostMapping(
value = "/compute")
public ResponseEntity<RiskFactorResponseDto>
computeRiskFactor(
@ApiParam(
value = "the request containing relevant
customer attributes (e.g., birthday)",
required = true)
@Valid @RequestBody
RiskFactorRequestDto riskFactorRequest) {
int age =
getAge(riskFactorRequest.getBirthday());
String postalCode =
riskFactorRequest.getPostalCode();
int riskFactor =
computeRiskFactor(age, postalCode);
return ResponseEntity.ok(
new RiskFactorResponseDto(riskFactor));
}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 Slack Web API is
processing-oriented with its
https://slack.com/api/METHOD_FAMILY.method syntax. It has
the notion of “HTTP RPC
methods” and even puts a command name in the resource URIs (which is
considered a REST anti pattern by some authors in the Web API design
community).
The layers of the Domain-Driven
Design Sample Application, characterized here,
implement (local) interfaces for
Processing Resources,
BookingService.java and
CargoInspectionService.java.
You can find instances of Processing Resources in most integration architectures. Service-Oriented Architectures (SOAs) in enterprises often feature services exposing business capabilities rather than data abstractions in their interfaces; each of these services is a Processing Resource. An early example that went into production in early 2003 is the Dynamic Interface of a core banking backend described in an OOPSLA 2004 experience report and in Brandner et al. (2004).
Terravis provides a process hub for enabling fully digitalized mortgage processes between Swiss land registries, banks, notaries and other parti. It uses a variety of Command Services (e.g., Contract Signing) to trigger actions in partners when coordinating inter-organizational business processes Lübke and Lessen (2016).
More examples for usage of the pattern in a business information system (a.k.a. enterprise application) context can be found in the telecommunications order management SOA described in Zimmermann et al. (2005). This SOA introduces the notion of business services and application services.
More Information
Related Patterns
Processing Resources may contain operations hat differ in the way they deal with provider-side state (stateless services vs. stateful processors): State Transition Operation, State Creation Operation, Computation Function, and Retrieval Operation (some of which in turn have variants). These specializations also differ w.r.t. client commitment and expectations as expressed in pre- and postconditions and request and response message signatures in the API contract. The Information Holder Resource pattern represents opposite semantics and is an alternative to this pattern.
Processing Resources are commonly exposed in Community APIs and Public APIs; if this is done, they can be protected with an API Key and Rate Limits. Their usage is often governed by a Service Level Agreement that accompanies the technical API Contract. To avoid that technical parameters creep into the payload in request and response messages, such parameters can be isolated in a Context Representation.
The three patterns Command Message, Document Message and Request-Reply Hohpe and Woolf (2003) are used in combination when realizing this pattern. The Command pattern in Gamma et al. (1995) codifies a processing request and its invocation data as an object and as a message, respectively.1
This pattern and its operation-level companions (see above) can be seen as the remote API variant of the general Command pattern in Gamma et al. (1995) and Application Service in Alur, Malks, and Crupi (2013). Its provider-side implementations often use a Service Activator Hohpe and Woolf (2003).
Other Sources
Processing Resources correspond to interfacers that provide and protect access to service providers in Responsibility-Driven Design (RDD) Wirfs-Brock and McKean (2002). Domain-Driven Design (DDD) Evans (2003) and this pattern are also related in several ways:
- DDD Services are good candidates for remote interface exposure.
- A DDD Bounded Context can map and correspond to an API (with several endpoints).
- A DDD Aggregate can also map and correspond to an API (with several endpoints, starting with the root entity).
- DDD Factories and Repositories deal with entity lifecycle management, which involves read and write access to API provider-side application state.
- DDD Value Objects can be exposed as Data Transfer Representations (DTRs) in the Published Language established by the data part of the API Description (a.k.a. service contract).
Chapter 6 in “SOA in Practice” Josuttis (2007) is on service classification; it compares several taxonomies including the one from “Enterprise SOA” Krafzig, Banke, and Slama (2004). Some of the examples in the process services type/category in these SOA books qualify as known uses (these books also include project examples/case studies from domains such as banking and telecommunications).
The online article “Understanding RPC Vs REST For HTTP APIs” talks about RPC vs. REST, but taking a closer look it actually (also) is about deciding between Processing Resource and Information Holder Resource.
The action resource topic area/category in the API Stylebook provides a (meta) known use for this pattern. Its undo topic is also related.