| Scope | Phases | Roles | Activities | Abstraction/Refinement Level |
|---|---|---|---|---|
Remote service layer of backend |
Late analysis, early design (any iteration) |
Service Designer, Integration Architect |
Stepwise/Incremental Service Design (Contract First), Step 4 |
Technology-agnostic, platform-independent |
also known as: Preliminary Endpoint List, Draft API Plan, Initial API Roadmap, Resource Candidates
A candidate endpoint list outlines an initial API design, derived from analysis results.
Let us articulate the need for this artifact in question form:
How can an initial, draft set of API capabilities (i.e., responsibilities, collaborations) be compiled as these capabilities are identified in new requirements, design artifacts, and descriptions of existing systems (for instance, domain-driven designs, user interface mockups, integration stories)?
Step 4 in the Stepwise Service Design activity in DPR concerns remote service layer design; the API exposed by a service provides remote facades (@Fowler:2002). The still technology- and platform-independent output of this step is the Candidate Endpoint List (CEL); an endpoint candidate may be a remote facade.
Mike Amundsen's seven-step Web API design method starts with "List all the things"; this activity roughly corresponds to Steps 1 to 3 in DPR. Arnaud Lauret proposes an "API goal canvas" in Chapter 2 of "The Design of Web APIs" (@Lauret:2019).
Who wants to do what and how? What are the inputs and outputs? Which goals result?
A simple table will suffice:
| Endpoint | Operation | Role/Exposed Data |
|----------|-----------|-------------------|
|... |... |... |
Microservice API Patterns Tutorial 2 provides a customer master-data management example. In the tutorial, the following user story (complemented with architectural context information, NFRs, and a simple domain model) provides the primary input to the API design activities:
"As a customer of Lakeside Mutual, I want to update my contact information myself online so that I can make sure that the data is entered correctly and I do not have to call an agent, which may involve long waiting times."
A CEL identifying the API design and frontend-backend integration needs derived from this story looks like this (note that HTTP verbs are already called out, which might be a little early):
| Endpoint | Operation (HTTP verb) | Role/Exposed Data |
|---|---|---|
| Customer | Find (GET) | Returns list of identifiers of customers that match some search criteria |
| Read (GET) | Returns details of one particular customer record | |
| Update (PUT) | Allows client to change all or parts of a customer record (for instance, address and context information) |
Any plain text or Markdown editor, wikis, presentation tools (and even spreadsheets) can be used to create and populate CEL tables, as long as they provide some support for table editing.
Taking the output of Step 3 in the Stepwise Service Design activity (or equivalent output of any business analysis and architecture design method) into account, you may want to follow the following steps when populating the CEL table (and, in the next step, the Refined Endpoint List (REL)):
- Add one candidate API per functional partition, for instance expressed as DDD Subdomain (@Evans:2003) or Bounded Context (@Vernon:2013); optionally, also add one candidate endpoint per Entity and Service in a Subdomain and/or Aggregate in a Bounded Context.
- Add one candidate API per layer that crosses a physical tier boundary according to the chosen assignment of logical layers to physical tiers, also known as client-server cuts (@RenzelKeller:1997). For instance, add one candidate API per client application as explained/motivated in the Backends-for-Frontends pattern.
- Refactor (merge, split) to remove redundant candidate endpoint entries and achieve high cohesion (w.r.t. business-/domain-level responsibilities) within endpoints.
A general hint is not to hesitate to undo and revise as you learn more about the client's information needs and provider capabilities (both on CEL and REL level).
Any design/documentation artifact in between a planning item/requirement specification (for instance, a user story) and annotated source code providing a RESTful HTTP (or similar) endpoint resource qualifies as a CEL.
The CEL and REL artifacts in DPR originate from the MAP project, mining experiences in the community. Similar artifacts appear in "Build APIs You Won’t Hate" (@Sturgeon:2016) and "Design and Build Great Web APIs" (@Amundsen:2020). Chapter 2 of "The Design of Web APIs" (@Lauret:2019) features an "API Goals Canvas", which also is very similar to the CEL/REL artifacts in DPR.
- Use Cases or User Stories as well as User Interface Mockups can serve as input to CEL preparation.
- The same holds for the Domain Model.
- Architecture Overview Diagrams and models containing a (Remote) Service Layer
- The Refined Endpoint List picks up the CEL en route to implementation.
- API Description, capturing platform-independent and -specific service contracts (MDSL, OpenAPI Specification, AsyncAPI)
- Phil Sturgeon's "Build APIs You Won't Hate" (@Sturgeon:2016) features a simple but effective resource identification technique and a simple table format for CELs.
- Mike Amundsen's seven-step Web API design method uses finite state machines as an intermediate artifact (@Amundsen:2020).
- James Higginbotham has posted API design advice on the Tyk blog, for instance he advises "Before you design your API, model your API" in five steps. The API model produced in the fourth step corresponds to the CEL here in DPR.
title: "Design Practice Repository (DPR): Candidate Endpoint List"
author: Olaf Zimmermann (ZIO)
date: "03, 31, 2021"
copyright: Olaf Zimmermann, 2020-2021 (unless noted otherwise). All rights reserved.
license: Creative Commons Attribution 4.0 International License