Responsibility Patterns

The patterns in the responsibility category clarify the architectural roles of API endpoints and the responsibilities of their operations.

Foundation Patterns Structure Patterns

Category Overview

The Responsibility Patterns category comprises the following patterns:

Responsibility

Endpoint Roles

Pattern: Processing Resource
Problem How can an API provider allow its clients to trigger an action in it?
Solution Add a Processing Resource endpoint to the API exposing operations that bundle and wrap application-level activities or commands.
Pattern: Information Holder Resource
Problem How can domain data be exposed in an API, but its implementation still be hidden? How can an API expose data entities so that API clients can access and/or modify these entities concurrently without compromising data integrity and quality?
Solution Add an Information Holder Resource endpoint to the API, representing a data-oriented entity. Expose create, read, update, delete, and search operations in this endpoint to access and manipulate this entity. In the API implementation, coordinate calls to these operations to protect the data entity.

Information Holder Types

Pattern: Operational Data Holder
Problem How can an API support clients that want to create, read, update, and/or delete instances of domain entities that represent operational data: data that is rather short-lived, changes often during daily business operations, and has many outgoing relations?
Solution Tag an Information Holder Resource as Operational Data Holder and add API operations to it that allow API clients to create, read, update, and delete its data often and fast.
Pattern: Master Data Holder
Problem How can I design an API that provides access to master data that lives for a long time, does not change frequently, and will be referenced from many clients?
Solution Mark an Information Holder Resource to be a dedicated Master Data Holder endpoint that bundles master data access and manipulation operations in such a way that the data consistency is preserved and references are managed adequately. Treat delete operations as special forms of updates.
Pattern: Reference Data Holder
Problem How should data that is referenced in many places, lives long, and is immutable for clients be treated in API endpoints? How can such reference data be used in requests to and responses from Processing Resources or Information Holder Resources?
Solution Provide a special type of Information Holder Resource endpoint, a Reference Data Holder, as a single point of reference for the static, immutable data. Provide read operations, but no create, update, or delete operations in this endpoint.
Pattern: Link Lookup Resource
Problem How can message representations refer to other, possibly many and frequently changing, API endpoints and operations without binding the message recipient to the actual addresses of these endpoints?
Solution Introduce a special type of Information Holder Resource, a dedicated Link Lookup Resource endpoint that exposes special Retrieval Operation operations that return single instances or collections of Link Elements that represent the current addresses of the referenced API endpoints.
Pattern: Data Transfer Resource
Problem How can two or more communication participants exchange data without knowing each other, without being available at the same time, and even if the data has already been sent before its recipients became known?
Solution Introduce a Data Transfer Resource as a shared storage endpoint accessible from two or more API clients. Provide this specialized Information Holder Resource with a globally unique network address so that two or more clients can use it as a shared data exchange space. Add at least one State Creation Operation and one Retrieval Operation to it so that data can be placed in the shared space and also fetched from it.

Operation Responsibilities

Pattern: State Creation Operation
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?
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.
Pattern: Retrieval Operation
Problem How can information available from a remote party (the API provider, that is) be retrieved to satisfy an information need of an end user or to allow further client-side processing?
Solution Add a read-only operation `ro: (in,S) -> out` to an API endpoint, which often is an Information Holder Resource, to request a result report that contains a machine-readable representation of the requested information. Add search, filter, and formatting capabilities to the operation signature.
Pattern: State Transition Operation
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?
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.
Pattern: Computation Function
Problem How can a client invoke side-effect-free remote processing on the provider side to have a result calculated from its input?
Solution Introduce an API operation `cf` with `cf: in -> out` to the API endpoint, which often is a Processing Resource. Let this Computation Function validate the received request message, perform the desired function cf, and return its result in the response.