Pattern Sections
Pattern: Data Element 
a.k.a. Text Element, Payload Content, Data Representation
Context
API endpoints and their operations have been identified. For instance, in forward engineering, the key domain concepts to be exposed and their relationship have been elicited on a high level, e.g., in the form of a domain model. In the context of system evolution and modernization, it has been decided to open up an existing system via an API endpoint, or make the content of an existing database available this way.
An API goals overview (Lauret (2019)) or API an action plan (Sturgeon (2016)) is available. The usage of basic structure patterns has been discussed and/or decided initially, but the request and response message design yet has to be finalized. The data that has to be exchanged may be part of (or influence) the persistent application state.1
Problem
How can domain/application-level information be exchanged between API clients and API providers without exposing provider-internal data definitions in the API? How can API client and API provider be decoupled from a data management point of view?
Forces
In addition to the already stated intent to promote loose coupling, the following competing forces make the design of interface data model hard, especially concerning the decision of which data elements should be directly exposed and which ones should be wrapped or kept hidden behind the interface:
- Loose coupling
- Rich functionality versus ease of processing and performance
- Security and data privacy versus ease of configuration
- Maintainability versus flexibility
Pattern forces are explained in depth in the book.
Solution
Define a dedicated vocabulary of Data Elements for request and response messages that wraps and/or maps the relevant parts of the data in the business logic of an API implementation.
Sketch
A solution sketch for this pattern from pre-book times is:
Example
The following excerpt from the solution-internal API of a Customer
Relationship Management (CRM) system features strongly typed
Data Elements, a structured one
(name) and a flat one (phoneNumber):
data type Customer {
"name": ("first":D<string>, "last":D<string>),
"phoneNumber":D<string>
}
endpoint type CustomerRelationshipManagementService
exposes
operation getCustomer
expecting payload "customerId": ID
delivering payload CustomerCustomer is a
Parameter
Tree that combines the two data elements. The example also features
an
Atomic
Parameter and
IdElement,
customerId. Note that these data representations might have
been identified with and might be implemented in a Domain
Model; that said, the domain model elements should not be exposed
directly if loose coupling of client, interface, and implementation is a
desired principle.
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
It is hard to imagine any domain-specific API that does not feature at least a few Data Elements. Hence, known uses of this pattern are ubiquitous; to list just three Public APIs that expose domain entities:
- In the Twitter API, tweets travel as instances of this pattern.
- In the GitHub API, users, projects, and commits qualify as known uses.
- The Stripe API works with clients, bills, and online payments.
In the Stripe API supporting financial transactions, the “Balance” object and all other “core resources” are represented as Data Elements when transferred from/to API clients. The Balance History, for instance, looks like this:
{
"object": "list",
"url": "/v1/balance/history",
"has_more": false,
"data": [
{
"id": "txn_19XJJ02eZvKYlo2ClwuJ1rbA",
"object": "balance_transaction",
"amount": 999,
"available_on": 1483920000,
"created": 1483315442,
"currency": "usd",
"description": null,
"fee": 59,
"fee_details": [
{
"amount": 59,
"application": null,
"currency": "usd",
"description": "Stripe processing fees",
"type": "stripe_fee"
}
],
"net": 940,
"source": "ch_19XJJ02eZvKYlo2CHfSUsSpl",
"status": "pending",
"type": "charge"
},
{...},
{...}
]
}Customer relationship management, contract management and risk management systems in the insurance domain (for instance using Backend Integration and a Community API) often use this pattern (Zimmermann, Tomlinson, and Peuser (2003)). Core banking integration solutions transfer entities such as accounts and financial products Brandner et al. (2004).
Siren, a
hypermedia specification for representing entities, implements the
entity variant of the pattern in JSON in the form of entites
and sub-entities. URIs serve as identifiers; actions “show
available behaviors an entity exposes”. The media type for JSON Siren is
application/vnd.siren+json.
More Information
Related Patterns
Data Elements travel in Parameter Trees and Parameter Forests. Master Data Holder and Operational Data Holder are two patterns that distinguish two types of information-oriented endpoints; read and write access to such endpoints requires Data Elements.
An Data Element can represent instances of the Entity and Value Object patterns in Domain-Driven Design (DDD) (Evans (2003)) in transit. That said, one should be aware that instances DDD patterns should not be translated into API designs one-to-one. While an Anti-Corruption Layer can protected the downstream participant in a relation (here: API client), the upstream (here: API provider) should design its Published Language in such a way that undesired coupling is minimized (Vernon (2013)).
Alur, Malks, and Crupi (2013) presents a Data Transfer Object pattern for usage within an application boundary (e.g., data transfer between tiers). Fowler (2002) touches on many aspects of remote API design such as Remote Facades or Data Transfer Objects (DTOs). Similarly, Evans (2003) touches on functional API aspects such as Bounded Contexts and Aggregates as part of his DDD patterns. Instances of these patterns contain multiple entities; hence, they can be used to aggregate Data Elements into coarser grained units.
The general data modeling patterns in Hay (1996) cover data representations, but focus on data storage and presentation rather than data transport (therefore, the discussed forces differ). Domain-specific modeling archetypes for enterprise information systems also can be found in the literature (Arlow and Neustadt (2004)).
The Cloud Adoption Patterns website has a process pattern Identify Entities and Aggregates.
Other Sources
Chapter 3 in the RESTful Web Services Cookbook by Allamaraju (2010) gives representation design advice (in the context of HTTP); for instance, recipe 3.4 discusses how to choose a representation format and a media type (with Atom being one of the options).
The Software/Service/API Design Practice Repository (DPR) features Domain-Driven Design and other patterns and practices eligible in API and data contract design.
Context Mapper clarifies the relationships between strategic DDD patterns in its DSL and tools.
References
The application state data/elements may, for example, contain instances of concepts from the domain model of the system underlying the API. ↩︎