Pattern: Atomic Parameter

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?


The final version of this pattern is featured in our book Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges.

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:

Figure 1: Atomic Parameter pattern: single scalar parameter (here: in parameter in request message)

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-78a10ae3e3bd

This 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

Evans, Eric. 2003. Domain-Driven Design: Tacking Complexity in the Heart of Software. Addison-Wesley.
Hohpe, Gregor, and Bobby Woolf. 2003. Enterprise Integration Patterns: Designing, Building, and Deploying Messaging Solutions. Addison-Wesley.


  1. The example is publicly available on GitHub: https://github.com/web-apis/riskmanagement-server.↩︎