Pattern Sections
Pattern: Id Element 
a.k.a. Identifier Element, Unique Identifier, Id Representation
Context
A domain model representing the core concepts of an application or software (eco-)system has been defined and implemented. Remote access to the domain model implementation is under construction (for instance, HTTP resources, Web service operations, or gRPC service methods) to support architectural principles such as loose coupling, independent deployability, and isolation, the I in POINT).
The domain model consists of multiple related elements that have different life cycles and semantics. Its currently chosen decomposition into remotely accessible API endpoints (for instance, exposed by a set of microservices) suggests that these related entities should be split up into several API elements (for instance, HTTP resources exposing methods, Web service port types with operations, or gRPC services and methods) to support principles such as loose coupling, independent deployability, and independent scalability. API consumers want to be able to follow the relationships between the remote services to satisfy their information and integration needs.1
Problem
How can API elements be distinguished from each other at design time and at runtime? When applying domain-driven design, how can elements of the Published Language be identified?
Forces
The following non-functional requirements have to be satisfied when addressing the identification problem:
- Effort versus stability
- Readability for machines and humans
- Security (confidentiality)
Pattern forces are explained in depth in the book.
Solution
Introduce a special type of Data Element, a unique Id Element, to identify API endpoints, operations, and message representation elements that have to be distinguished from each other. Use these Id Elements consistently throughout API Description and implementation. Decide whether an Id Element is globally unique or valid only within the context of a particular API.
Sketch
A solution sketch for this pattern from pre-book times is:
Example
Pagination cursors in the Twitter REST
API illustrate the pattern, for instance
next_cursor:
{
"data": [...],
"data_type": "campaign",
"next_cursor": "c-3yvu1pzhd3i7",
"request": {...},
"total_count": 200
}An auto-generated ID for the next_cursor has been
introduced. On the server side, the Twitter REST API implementation has
to be sure that this ID is unique at least until the user session
expires. It also has to store the association between this ID and the
next cursor position for this user session, so that the correct next
cursor is displayed, if the user requests the next_cursor
with this ID. This example also shows that the scope of the identifier
can be bound not only by space, but also time.
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
The Facebook Graph API identifies feeds by numeric identifiers such
as "id": "164202036981850_1277103665691676".
Heroku, a platform as a service cloud provider, and Docker, a
container platform, generate unique names that are human-readable to
identify service instances and containers, e.g.,
peaceful-reaches-47689 (Heroku) and
practical_carson (Docker).
LinkedIn uses URNs in its REST API “to represent foreign associations to an entity (persons, organizations, and so on)”.
Entities in Domain-Driven Design (DDD) have an identity and a lifecycle; hence, many Id Elements can be found in RESTful APIs within DDD implementations such as the Cargo Tracking sample application.
Globally unique identifiers are used in many domains; they appear as key concepts in many digitalization effort. Examples include publishing DOIs and ORCIDs as well as identifiers of legal entities issued by government (for instance, social security numbers, tax identifiers); domain-specific APIs then often work with such ids. For instance, the UID service offered by the Swiss government works with unique company identifiers.
A major German car manufacturer offers a REST level 2 user profile
management service for all its clients; this service uses a JSON object
with three key-value pairs to represent email addresses and changes to
them: {"_updated":"...", "email":"...","uuid":"..."}. The
elements in the object are a
Metadata
Element followed by a
Data
Element and an
Id
Element.
Terravis uses different identifiers for parcels called electronic parcel ID (“EGRIDs”, as “Grundstück” is German for parcel), rights (“EREIDs”, electronic rights ID), and persons (“EGBPIDs”, electronic land register person ID) to refer to these objects in a location-transparent manner. Elements carrying these IDs can be found in many requests and responses sent between Terravis and its partners (Lübke and Lessen (2016)).
More Information
Related Patterns
Link Element is a closely related pattern that not only makes (remote) references to API elements globally unique, but also network-accessible. Both Link Element and Id Element are special types of Data Elements. Unlike Link Elements, Id Elements do not contain network-accessible addresses; Id Elements typically also do not contain semantic type information.
An Id Element can travel as an Atomic Parameter (but also be contained in any other structural representation pattern). API Keys and Version Identifiers can be seen as special kinds of identifiers. Master Data Holders often require strong identification schemes because of their longevity; Operational Data Holders typically are identified uniquely as well. The data elements returned by Reference Data Holders may serve as Id Element, for instance, zip codes identifying cities (or parts of them). Link Lookup Resources may expect Id Elements in requests and deliver Link Elements; Data Transfer Resources use locally or globally unique Id Elements to define the transfer units and/or storage locations; examples of such design can be found in cloud storage offerings such as AWS Simple Storage Service (S3) with its URI-identified buckets.
A Correlation Identifier and a Return Address as well as the keys used in the Claim Check and the Format Identifier patterns in Hohpe and Woolf (2003) are related patterns. Like in the referenced patterns (that have a different context), the creation of a unique ID is required here.
Microservice Design in Cloud Adoption Patterns discusses domain-driven design and service identification.
Other Sources
Wikipedia has an introduction to UUIDs.
Five API design principles are introduced in the blog post “APIs should get to the POINT”. Using Id Elements can help achieve a T-shape because certain operations can return lists of identifiers (horizontal bar of the T) while others provide detailed information about the identified elements (vertical bar of the T). Moreover, providing and identifying adequate abstractions promotes style-orientation (for instance, URI pointing at resources in REST).
The distributed systems literature discusses general naming, identification and addressing approaches (for instance, Tanenbaum and Van Steen (2007)). RFC 4122 describes the basic algorithm for random number generation (UUID/GUID).
References
Note that this context is the picked up and refined by that of the Link Element pattern.↩︎