Getting Started with API Design

Foundation patterns address the early and basic API scoping issues. Table A.1 lists such issues and corresponding patterns.

The selection of these patterns is driven by criteria such as type of client, business model, product/project vision, and project/product context. The client portfolio (that is, number and location of clients, information needs of these clients), and security requirements are important criteria to consider. Chapters 1, 3, and 4 collect many more decision drivers and desired qualities.

Next up, in Table A.2, responsibility patterns can jumpstart API endpoint design.

During endpoint identification, one might decide to define one API or one API endpoint for each “Bounded Context” from DDD if logic and data are highly cohesive [Singjai 2021a]. If fine-grained decomposition is desired and possible, “Aggregate” may initiate API and API endpoint identification [Singjai 2021b; Singjai 2021c].

The operations exposed by API endpoints differ in the way they touch (or do not touch) provider-side state: read, write, read-write, or neither read nor write (Table A.3).

Designing Request and Response Message Structures

Once the roles and responsibilities of API endpoints and their operations have been characterized, it is time to specify the data contract (the structure of headers and body in request and response messages, that is). Table A.4 shows the different options.

Table A.5 shows how, in message payload design, both basic and structured message elements may receive certain stereotypical roles.

Improving API Quality

Patterns related to API quality can help solve interoperability issues and size message representations right if the goal is to achieve data transfer parsimony (Table A.6).

API Support and Maintenance

API providers have to deal with change and must balance compatibility and extensibility. The evolution patterns in Table A.7 cover strategies and tactics for doing so.

API Release and Productization

Once an API goes into production, documentation and governance tasks come into play. Table A.8 introduces some common issues and applicable patterns.

RDD Concepts

To order and structure the endpoint and operation design space (or, in ADDR, the Define phase), we adopt some of the terminology and the role stereotypes from RDD [Wirfs-Brock 2002]. RDD was originally created for the context of object-oriented analysis and design (OOAD), which becomes apparent in its core definitions:

• An application is a set of interacting objects.

• An object is an implementation of one or more roles.

• A role groups related responsibilities.

• A responsibility is an obligation to perform a task or know information.

• A collaboration may be an interaction of objects or roles, or a combination of both.

• A contract is an agreement outlining the terms of a collaboration.

In our experience, RDD works equally well on the code level and on the architecture level. As API design has both architectural and developmental ramifications, the role stereotypes in RDD are a natural choice to express API behavior. For instance, all API endpoints can be seen to have (remote) interfacers that provide and protect access to service providers, controllers/coordinators, and information holder roles. The read-write operations exposed by API endpoints correspond to responsibilities. The API DESCRIPTION specifies the RDD contract, and collaborations arise from calls to API operations.

The patterns in Chapter 5 pick up these terms and concepts for the context of API design.

DDD and API Design

DDD [Evans 2003; Vernon 2013] and our patterns are also related in several ways:

• DDD “Services” are good candidates for remote API exposure.

• A DDD “Bounded Context” may correspond to a single API (with several endpoints).

• A DDD “Aggregate” can also be exposed via an API (possibly having several endpoints, starting with the root “Entity”). Depending on the nature of an Aggregate, a PROCESSING RESOURCE is often preferred over an INFORMATION HOLDER RESOURCE; see the discussions in these two patterns for rationale.

• DDD “Repositories” deal with entity life-cycle management, which involves read and write access to API provider-side application state (as defined by our operation responsibility patterns). For instance, repositories usually provide lookup capabilities, which may turn into API-level RETRIEVAL OPERATIONS. Special-purpose repositories may yield LINK LOOKUP RESOURCES. DDD “Factories” also deal with life-cycle management and may donate additional API operations (unless their functionality should remain an API-implementation detail).

• DDD “Value Objects” can be exposed as data transfer representations (DTRs) in the Published Language established by the data part of the API DESCRIPTION. DATA ELEMENT from Chapter 6 is a related pattern.

In DDD, the Aggregate and Entity patterns often expose process-like properties (as they represent groups of domain concepts that have an identity and a life cycle at runtime). Hence, these patterns can help identify STATE CREATION OPERATION and STATE TRANSITION OPERATION candidates during endpoint identification. However, it is important not to expose the entire domain model as Published Language on the API level because this creates an undesired tight coupling between the API clients and the provider-side API implementation.

DDD does not distinguish between master data and operational data in its tactic patterns; both operational data and master data may be part of the Published Language and appear in dedicated Bounded Contexts and Aggregates as Entities (see [Vernon 2013]). In DDD, domain event sourcing [Fowler 2006] is the recommended practice to integrate Aggregates (both within the same and in different Bounded Contexts) because it decouples them and allows replaying events up to the current state in case of failures that lead to consistency issues. APIs may support this.

In Principles of Web API Design, James Higginbotham reminds us that “resources are not data models” and “resources are not objects or domain models” [Higginbotham 2021], with resources corresponding to endpoints in our technology-neutral terminology. And “REST was never about CRUD” either. That said, data and domain models may still serve as API design input when taken with a grain of salt.

ADDR and Our Patterns

Principles of Web API Design [Higginbotham 2021] also is the source of the ADDR process that we roughly followed in Part 2.

Table A.9 summarizes the correspondences between ADDR phases/steps and the patterns from this book. It also provides application examples from our sample case (note that some of the pattern selection decisions appeared in the narratives in Chapter 3).

More details on the Identify API Boundaries step. Our messages are very much in line with James Higginbotham’s advice; for instance, our patterns help avoid the antipatterns he discusses [Higginbotham 2021, p. 70 ff.]. By considering our end-point role patterns from Chapter 5 when deciding between activity- or data-oriented semantics of endpoints and being aware of the differences in the responsibilities of their operations, antipatterns like the “Mega All-In-One API,” “Overloaded API,” and “Helper API” can be avoided.

More details on the Model API Profiles step. This is an ADDR step in which many of our patterns are eligible. For instance, the LINK ELEMENT pattern and related METADATA ELEMENTS from Chapter 6 may be used to describe the “resource taxonomies” (independent/dependent/associative resources) [Higginbotham 2021, p. 87], and the “operation safety classification” (safe/unsafe/idempotent operations) [p. 91] can be expressed with the operation responsibilities from Chapter 5.

More details on the High-Level Design step. This ADDR step is complementary to our Chapters 4, 5, and 7; the patterns from these chapters fit here. A RATE LIMIT (Chapter 9) can be part of the “API Management Layer.” Deciding whether to include related or nested resources, discussed in the context of “hypermedia serialization” [Higginbotham 2021, p. 127], is covered by our EMBEDDED ENTITY and LINKED INFORMATION HOLDER patterns. Our WISH TEMPLATE pattern provides complementary advice on “query-based APIs.”

More details on the Refine the Design step. Note that optimizing for performance on a platform-neutral level (as our Chapters 6 and 7 patterns do) is not covered as such in ADDR. That said, our Chapters 6 and 7 patterns belong to this phase and step in ADDR. Higginbotham’s process and our patterns complement each other here.