design-practice-repository

Artifact/Template: Refined Endpoint List (REL)

also known as: Ordered Endpoint List, Final API Action Plan, Detailed API Roadmap, Resource Specifications

A refined endpoint list records intermediate API design results on a medium level of abstraction/refinement and detail, showing endpoints with their responsibilities and data contracts.

Motivation (Addressed Information Need)

A REL answers the following questions:

How can high-level specifications for the required API operations be added to the endpoint descriptions (without getting lost in syntactic details or “review wars” caused by technology beliefs)?
In particular, how can API endpoint and operation responsibilities be found and captured rapidly (without engaging in premature detailed decision making)?

Usage (Produced and Consumed When)

A Refined Endpoint List (REL) is produced in Step 5 in Stepwise Service Design, remote service layer design (the API provides the remote facades).

Mike Amundsen’s seven-step Web API design method includes “Reconcile Magic Strings” as Step 3 and “Select a Media Type” as Step 4 (@Amundsen:2020); REL creation and population roughly corresponds to these two steps. The REL corresponds to the “updated API goal canvas” that Arnaud Lauret proposes in Chapter 2 of “The Design of Web APIs” (@Lauret:2019).

Template Structure and Notation(s)

Record your design results in list or table form. Start with a list of endpoints with their visibility and direction and link to requirements and domain model, for instance structured as this:

API name:  [name]

Identified in: [user story, domain model element, architecture diagram]
Direction: (Frontend Integration | Backend Integration)
Visibility: (Public API | Community API | Solution-Internal API )

Endpoints in this API (and their architectural role): 

1. Endpoint (EP) 1: [name], [role]
2. EP 2: [name], [role]
3. EP 3: [name], [role]

For each API endpoint in such list, specify its responsibilities and signature on a platform- and technology-neutral, yet concrete level of detail:

| Endpt. | Op.    | Responsibility | Request and Response Message | Media Type |
|--------|--------|----------------|------------------------------|------------|
| [name] |        | [endpt. role]  |                              |            |
|        | [name] | [op. resp.]    | [abstract data contract]     | [DIY, IANA]|
| ...    |        |                |                              |            |
|        | ...    |                |                              |            |

Design elaboration. Make the following decisions and record them as described in the activity Architectural Decision Capturing:

Communication protocol (HTTP? gRPC? GraphQL?) including REST maturity level when using HTTP (from 0 to 3, HATEOAS)
Message exchange format, for instance MIME type when using RESTful HTTP (refining a platform-neutral DTO design in UML or MDSL): JSON? XML? Other message exchange format?
Media/content type profile: Application-Level Semantic Profiles (ALPS)? JSON-LD + Hydra? Microformats?
Security design (CIA) decisions (details out of scope here)

Decide with an API-wide scope or decide separately per endpoint/per operation if the Non-Functional Requirements require such differentiation. Update your Architecture Modeling artifacts from previous steps accordingly.

Example(s)

This example of a REL continues and details the example given in the Candidate Endpoint List (CEL) artifact:

Endpoint	Operation (HTTP verb)	Responsibility Pattern (MAP)	Published Language (Request and Response Message Payload)	Media Type/Profile
Customer		Master Data Holder		Microformats or ALPS (tbd)
	Find (GET)	Retrieval Operation	in: QueryString (tbd), out: CustomerDTOSet
	Read (GET)	Retrieval Operation	in: `CustomerId":ID<int>`, out: `CustomerDTO`
	Update (PUT)	State Creation Operation	in: `{"CustomerId", "newPhoneNumber", "newAddress"}`, out: `{"statusInformation", "linkToUpdatedCustomerResource}`

Note that one could use a structure that deviates from the template. This is ok according to our second rule of method adoption: “do not follow templates blindly, but adopt them to your needs”.

Tools

A few examples of tools include:

The Freemarker generator in the MDSL tools can generate Markdown reports formatted according to the above suggestions for RELs.
SwaggerHub and its competitors support OpenAPI; SoapUI supports both WSDL/XML schema and RESTful HTTP. A REL provides the input to technology-specific API design and implementation within such tools.
JHipster can be used to quickly turn OpenAPI specifications into Spring Boot applications.

Hints and Pitfalls to Avoid

Do not mechanically turn all application domain (micro-)layer artifacts such as Domain-Driven Design (DDD) pattern instances or facades into (micro-)services, but follow a recognized or homegrown identification method. For instance, the DDD Bounded Context is seen to form an upper boundary for microservice size, while Aggregates serve as lower boundary.
Reuse already modeled data representation elements if possible (for instance, consider microformats or schema.org).
Prioritize the non-functional requirements as many of them conflict with each other. Define a Service Level Agreement with at least one service level objective per operation (or endpoint).
Specify at least one API test case per User Story and API operation. Evaluate whether your API design and implementation can benefit from Test-Driven Development (TDD) and Behavior-Driven Development (BDD) and supporting tools such as Cucumber.

The book “Implementing Domain-Driven Design” by Vaughn Vernon (@Vernon:2013) provides the following more platform- and technology-specific advice (enhanced with insights from blog posts and presentations):

Avoid 1:1 pass-through between layers (in particular, interface layer and application/domain layer).
When Bounded Contexts are realized by API providers, one service API and IDE project for each team/system Bounded Context (a.k.a. microservice) should be foreseen.
Aggregates supply API resources (or responsibilities) of service endpoints.
DDD (application) services may be exposed as top-level (home) resources in Bounded Context endpoints as well.
The Root Entity (also known as Aggregate Root), the Repository, and the Factory in an Aggregate suggest top-level resources; contained entities yield sub-resources. The MDSL generator in Context Mapper implements this mapping.
Repository lookups become paginated queries (GET with search parameters).

Additional rules of thumb regarding the transition from DDD (@Evans:2003) to API design (drawn from our experience and additional sources) are:

Master data and transactional data go to different Bounded Contexts/Aggregates and, in turn, endpoints.
Creation requests to Factories become POSTs.
Entity modifiers become PUTs or PATCHes.
Value Objects appear in the custom MIME types representing resources.

The Cloud Adoption Patterns website has additional advice to give.

Origins and Signs of Use

The CEL and REL artifacts in DPR originate from the MAP project, mining experiences in the community.

Usage of the above list and table formats is a sign of use.

More Information

Service Layer and related patterns (@Fowler:2002)
Books on Web API design and RESTful HTTP (@Allamaraju:2010, @Lauret:2019) as well as related blog posts such as those by James Higginbotham
gRPC guidelines, for instance this style guide
GraphQL learning resources
WSDL/SOAP tips and tricks (@Zimmermann:2003)

Data Provenance

title: "Design Practice Repository (DPR): Refined Endpoint List (REL)"
author: Olaf Zimmermann (ZIO)
date: "1, 31, 2023"
copyright: Olaf Zimmermann, 2020-2021 (unless noted otherwise). All rights reserved.
license: Creative Commons Attribution 4.0 International License