ADDR Refine Phase Overview

The Refine Phase incorporates fast feedback to improve the API design through the use of documentation, prototyping, and testing efforts.

Step 6: Refine the Design

With the high-level API design completed and captured into an OAS document for sharing, additional work should be completed to help obtain feedback. This includes generating a sequence diagram showing how your API design is used to deliver on the job story outcomes.

Below is an example of how the API would be used to support an ecommerce shopping experience:

Example of a web sequence diagram for our REST API design: An example of a web sequence diagram for our REST-based API

Communicating the intended usage of your APIStatic mocks, such as those captured in JSON or XML, along with prototypes or mock implementations are useful in communicating how your API will work. These mocks are also useful for exploring a design before the coding begins and to speed-up front-end development by working in parallel with the API implementation.

Composing README-style documentation

Another technique that is useful is to write-up a README-style explanation of how the API should be used for common scenarios. Capture each step of using your API to deliver upon the job story outcomes identified in the Align Phase. This can include a sequence of request and responses:

README Documentation for Job Story #2: Plan a Trip:


GET /forecast?date=yyyy-mm-dd&locationName=Dallas HTTP/1.1
Accept: application/vnd.api+json

HTTP/1.1 200 OK
Content-Type: application/json
...

{
  "forecast": {
    ...
  }
}

Improve your API design reviewsAll of these assets are useful for an API design review, as they not only capture the API reference documentation, but they also demonstrate how it is intended to be used. It is recommended to share some or all of these assets prior to an API design review to better communicate intent for API usage, rather than just reference documentation such as an OpenAPI Specification document.

Techniques for refining the API design are covered in Chapter 11 of the book.

Step 7: Complete the API Documentation

The final step in API design is to complete the documentation for the API. So far, we have produced reference documentation by creating an OAS document (for a REST-based API) or an SDL (for GraphQL APIs), some diagrams, and README-based documentation. Using these assets, expand the documentation using Getting Started guides to help onboard developers quickly. Code examples and other supplemental documentation may also be used.

Techniques for improving your API documentation may be found in Chapter 13 of the book.

Back to homepage