design-practice-repository

Summaries of artifacts, templates, practices, and techniques for agile architecting (DPR-mm) and service design (SDPR-nn).

DPR Git Pages HomeArtifacts Index

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:

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:

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:

Hints and Pitfalls to Avoid

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):

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

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

Data Provenance

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