Pattern Sections
Pattern: Atomic Parameter
also known as: Single Scalar Representation, Dot
Context
An API provider wants to offer one or more Operations to API clients using an API endpoint. To enable the communication, they need to agree on the structure of each message (i.e., the request message and response message of the Operation) to be exchanged.
Problem
How can simple, unstructured data (such as a number, a string, a Boolean value, or a block of binary data) be exchanged between API client and API provider?
Forces
The data structures of the request messages and response messages are an essential part of the API contract. The following forces (shared with Atomic Parameter List, Parameter Tree, and Parameter Forest) need to be balanced:
- Structure of the domain model and the system behavior and its impact on understandability (including considerations of simplicity, complexity, and traceability)
- Additional data to be transmitted (such as security-related data or metadata)
- Performance (latency, message processing) and resource use (bandwidth, memory, CPU power)
- Loose coupling and interoperability
- Developer convenience and experience
- Security and data privacy
Pattern forces are explained in depth in the book.
Solution
Define a single parameter or body element. Pick a basic type from the type system of the chosen message exchange format for it. If justified by receiver-side usage, identify this Atomic Parameter with a name. Document name (if present), type, cardinality, and optionality in the API Description.
Sketch
A solution sketch for this pattern from pre-book times is:
Example
Our RESTful HTTP and JAX-RS examples1 use
instances of this pattern, for instance in the request message used to
GET (and PUT) claims by ID. Consider the following invocation to the
resource claims for the claim ID
a1e00494-e982-45f3-aab1-78a10ae3e3bd:
curl http://localhost:8080/claims/a1e00494-e982-45f3-aab1-78a10ae3e3bdThis Atomic Parameter can be read from the URL in JAX-RS as follows:
@GET
@Path("/{claimId}")
public ClaimDTO getClaimById(@PathParam("claimId") UUID claimId) {
return claims.findById(claimId).map(ClaimDTO::create).orElseThrow(noSuchClaim);
}Alternatively, an Atomic Parameter could be transported as
part of the query string of the URL (after a question mark
?) - this option should basically be chosen for any
Atomic Parameter that is transported in the URL and not an ID.
Another alternative is to put an Atomic Parameter into the body
of the message, e.g. encoded in JSON:
{
"id": "a1e00494-e982-45f3-aab1-78a10ae3e3bd"
}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
Most if not all message-based remote APIs use this pattern
frequently, for instance when requesting the status of a long running
business transaction (activity) by process ID. For example, the
createBucket call in the Web API of Amazon Web Service
(AWS) Simple Storage Service (S3) uses this pattern to define a simple
bucketName string as its input parameter (see the S3
API Console and SDK. Other examples are the response message of the
WSDL of
S3 Web Service API and the XML Schema
for S3).
In RESTful HTTP, URIs and in particular URI query strings can carry
instances of this pattern (particularly for GET method requests). For
instance, the Facebook
Graph API uses an Atomic Parameter event-id as
an input parameter in its endpoint URI.
The scalar value types of messages created with the Protocol Buffers data interchange format originally developed by Google and open sourced at GitHub can also be seen as instances of the Atomic Parameter pattern. The same holds true for the primitive types in Apache Avro, which are serialized into JSON.
The Web API specification language Swagger has the notion of a parameter object to “describe a single operation parameter”.
More Information
Related Patterns
Atomic Parameter is used in the three patterns Atomic Parameter List, Parameter Tree, and Parameter Forest as part of their structure, i.e., as a list element or leaf of the tree. All four patterns are alternatives in the two main decisions of the Structural Representation category, Atomic Parameter being the most primitive option.
This pattern can be used in the three patterns Command Message, Document Message, and Event Message from Hohpe and Woolf (2003), if the content can be represented as a scalar. For instance, a scalar command is quite conceivable. A scalar event is possible, but Event Message often contains other information (like a time-stamp and other metadata). Then Atomic Parameter List or Parameter Tree are a better representation structure. A Document Message is usually transported as a more complex data structure like a Parameter Tree, but sometimes documents are referenced by links and for such Document Messages containing links Atomic Parameter is a good representation structure.
References
The example is publicly available on GitHub: https://github.com/web-apis/riskmanagement-server.↩︎