Summaries of artifacts, templates, practices, and techniques for agile architecting (DPR-mm) and service design (SDPR-nn).
DPR Git Pages Home — Artifacts Index
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)):
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.
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