The ADDR API Design Process
Step 5: High-Level REST-based API Design
With the API profiles defined in the previous step, it is now possible to produce a high-level API design that delivers the job story outcomes identified previously, while offering the right API style for the target developer audience.
For REST-based APIs, this requires defining the resource URL paths, mapping each operation of the API profile to the corresponding HTTP method, and assigning HTTP response codes.
Below is the result, captured in a tabular format for easy editing before commiting to your design:
Example REST API Design Worksheet:
What about the OpenAPI Specification (OAS)?During the early stages of design, it is common for teams to capture their API design using the OpenAPI Specification. This can result in heavy rework efforts if you begin documentation too early in the process
While this is an important step, designs that require modification may require considerable time to rework the corresponding OpenAPI YAML document. Therefore, we recommend starting with a design worksheet then proceed to documenting your APIs using the OpenAPI Specification during the Refine Phase.
More details on designing REST-based APIs are found in Chapter 7 of the book.
There are similar steps associated with designing gRPC and GraphQL-based APIs, which is covered in Chapter 8 of the book.
If you need to design async APIs using Webhooks, WebSockets, and other async API styles, refer to Chapter 9 of the book.
Now that the high-level design has been completed, it is time to refine your API design by obtaining feedback with your initial set of API consumers.