Pattern: Atomic Parameter List

How can multiple related Atomic Parameters be combined in a representation element so that each of them stays simple, but their relatedness becomes explicit in the API Description and the runtime message exchanges?

Structure Category Overview


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 List

also known as: Multiple Scalar Representations, Dotted Line

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 multiple related Atomic Parameters be combined in a representation element so that each of them stays simple, but their relatedness becomes explicit in the API Description and the runtime message exchanges?

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, 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

Group two or more simple, unstructured data elements in a single cohesive representation element to define an Atomic Parameter List that contains multiple Atomic Parameters. Identify its items by position (index) or by a string-valued key. Identify the Atomic Parameter List as a whole with its own name as well if that is needed to process it in the receiver. Specify how many elements are required and permitted to appear.

Sketch

A solution sketch for this pattern from pre-book times is:

Figure 1: Iconic visualization of Atomic Parameter List pattern: multiple simple scalars are sent (here: in parameter of a request message)

Variant: Atomic Parameter Collection

If all entries in the ordered list have the same structure (and are identified by position rather than a key name or other identifier), the Atomic Parameter List becomes an Atomic Parameter Collection.

Example

Th parameter of the getRiskReport operation in the insurance Web services example from Zimmermann, Tomlinson, and Peuser (2003) is an instance of this pattern. It uses the following complex type containing a list of two integers:

<xs:complexType name="getRiskReportViaMultipleScalar">
    <xs:sequence>
      <xs:element name="startYear" type="xs:int"/>
      <xs:element name="numberOfYears" type="xs:int"/>
    </xs:sequence>
</xs:complexType>

In the following corresponding SOAP message body, an instance of this type is used:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
      <ns2:getRiskReportViaMultipleScalar xmlns:ns2="http://reports.insurance.irp.org/">
         <arg0>2015</arg0>
         <arg1>3</arg1>
      </ns2:getRiskReportViaMultipleScalar>
    </soap:Body>
</soap:Envelope>

The RESTful HTTP implementation of the risk management server, implemented with JAX-RS on the provider side, also applies this pattern in various request messages. Some are part of the URI because they are needed for dispatching the request message:

curl http://localhost:8080/riskreport?firstYear=2017&noOfYears=1

Others are part of the JSON data in the request message as they are dispatched to the operations handling the request:

curl http://localhost:8080/claims -H "Content-Type: application/json" -d '{"dateOfIncident":"2017-02-01", "amount": 2000 }'

Another example is a a response message (for the first request above, requesting the risk report) with an Atomic Parameter List consisting of five elements:

HTTP/1.1 200 OK
Date: Tue, 14 Feb 2017 08:52:29 GMT
Content-Type: application/json
Vary: Accept-Encoding
Content-Length: 102

[{"year":2017,"policyCount":42,
  "totalClaimValue":2000.0,"claimCount":1,
  "totalInsuredValue":1000000.0}]

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

Attaching multiple URI parameters to an HTTP GET method call in RESTful HTTP can be viewed as an instance of this pattern, as well as URI Templates as defined in RFC 6570. Multiple plain parameters in an HTTP POST request also qualify as pattern instances.

Facebook’s Graph API to GET information about events per user applies this pattern in its response message.

Twitter heavily uses this pattern in its API, for example to post a new tweet:

POST
https://api.twitter.com/1.1/statuses/update.json?status=Hi%20there&lat=47.2266&lon=8.8184

Messages created with the Protocol Buffers data interchange format (originally developed by Google and open sourced at GitHub) that only contain simple data types as field value types can also be seen as instances of this pattern.

Swagger and its successor OpenAPI have the notion of a parameters definitions object to “to hold parameters to be reused across operations”.

More Information

Related Patterns

The Atomic Parameter pattern can be seen as a simpler alternative to this pattern, but also as its building block. Once an Atomic Parameter List becomes too large, switching either to a Parameter Tree or a simple variant of Parameter Forest often is the next step in the evolution of the message and its representations.
Atomic Parameter List can use a Parameter Tree as a wrapper structure for transport, if the technology used supports no other way to transport multiple parameters, as explained above. Parameter Forest contains a list built from elements based on the other three patterns: Atomic Parameter, Parameter Tree, and Atomic Parameter List.

Like Atomic Parameter 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 list. For instance, a command with parameters or an event described by multiple data fields (ID, timestamp, etc.) can be represented as an ordered list. A Document Message is usually transported as a more complex data structure like a Parameter Tree, but if documents contain parts and they are not embedded in the message, a Document Message can be constructed as a list of links to document parts.

An Atomic Parameter List is usually used for the request message in Pagination containing the query parameters.

References

Gysel, Michael, Lukas Kölbener, Wolfgang Giersche, and Olaf Zimmermann. 2016. “Service Cutter: A Systematic Approach to Service Decomposition.” In Proc. European Conference on Service-Oriented and Cloud Computing (ESOCC), 185–200. Springer.
Hohpe, Gregor, and Bobby Woolf. 2003. Enterprise Integration Patterns: Designing, Building, and Deploying Messaging Solutions. Addison-Wesley.
Zimmermann, Olaf, Mark Tomlinson, and Stefan Peuser. 2003. Perspectives on Web Services: Applying SOAP, WSDL and UDDI to Real-World Projects. Springer.

Pattern Index

Foundation Patterns

Responsibility Patterns

Structure Patterns

Quality Patterns

Evolution Patterns

Cheat Sheet

Back to homepage