11 Building a change workflow around API design-first

Having defined an API, our next logical step is to start building it. When we do so, we will inevitably be missing something critical that will cause us pain down the road. We have to consider how changes to the API definition will be communicated when we’re not all in the same room—changes that result from issues found during implementation or evolving business requirements. Before we start implementing the code, we should take the time to set up a change workflow so that we’ll be able to adapt confidently as changes arise.

In terms of the action plan created in chapter 9, we’re currently within the draft/review cycle. We will iterate on the API definition until we’ve concluded its design, so that the next step of implementing it can begin.

Describing the API ahead of building it—taking an API design-first approach—while hugely beneficial, comes with trade-offs that we need to be aware of and have answers for. We’ll be looking at these trade-offs, specifically those related to making changes in the API definition and keeping everyone on the same page.

11.1 The problem

11.2 Communicating and reacting to change

11.3 GitHub as our workflow engine

11.3.1 A single source of truth

11.3.2 Suggesting a change

11.3.3 Agreeing on a change

11.3.4 A way of viewing changes (based on an older version)

11.4 Tying the GitHub workflow together

11.4.1 Setting up GitHub and the source of truth

11.4.2 Steps in our GitHub workflow

11.5 A practical look at the workflow

11.5.1 Creating and suggesting DELETE /jobs/{id}