How Breaking Changes Affect API Documentation

API consumer experience is degraded whenever documentation diverges from reality

An API breaking change is something you want to avoid at all costs. At least that's what most of you would agree with. If any breaking change introduces a functional obstruction how does it also affect the API documentation?

---

This article is brought to you with the help of our supporter, Scalar.

Scalar is a suite of powerful & customizable developer tools to help you at all stages of API development. Create beautiful API Documentation in a notion-like editing experience.

---

In simple terms, breaking changes are those "that introduce an incompatibility with a previous version" of the API, as I wrote in "Building an API Product." There are two main categories of incompatibilities. On the one hand, you have incompatibilities that happen because you're adding restrictions to one or more operations. And then, there are also incompatibilities whenever you remove one or more capabilities from the API.

Examples of the first category include changing the authentication or the authorization of certain operations, adding input validations that didn't exist before, limiting the amount or the frequency of requests, and adding a new required parameter or payload property. The second category is easier to understand as it generally involves removing an operation or, a whole feature of the API.

What do these breaking changes have to do with the API documentation? Whenever you introduce a change to your API there's a natural mismatch between what it does and what the documentation says it does. While it's straightforward to automatically update your API reference whenever you introduce changes, you can't say the same about the other parts of your documentation.

Let's first see how adding restrictions affects your API documentation and then let's explore what happens to the documentation when you remove capabilities.

Adding restrictions

Whenever you add a restriction to your API you're making it harder for consumers to use it. How those restrictions translate into information that you share through your documentation is crucial to offering the best possible experience to consumers.

So, for example, if you add a required parameter to an operation it's not enough to update your API reference. You also have to go through the other elements of your documentation and make sure they're up to date. That includes any how-tos, tutorials, code samples, and SDKs.

The impact of adding restrictions can be devastating if you're offering documentation that also includes video tutorials and other pre-recorded learning material. You'll have to make sure all elements are updated to reflect the breaking change you're introducing.

The best way I can think of to manage this situation is to create a list of documentation dependencies for each API operation. Whenever you make a change on one operation you'll know which dependencies you'll need to review and possibly update. Then, before you introduce the changes, update all documentation assets and synchronize the deployment of the new versions with the deployment of your API.

Another way, which is less elegant, is to mark each documentation dependency as outdated. You can do this by adding information to the documentation element explaining that it no longer reflects the latest API version. In the case of video or audio material, you can change its description or add a comment explaining the situation.

Removing capabilities

The second category creates a situation where some parts of your documentation become obsolete. While on the first category, the documentation misguides consumers, in this case, it shows capabilities that are no longer available. Documentation about capabilities that no longer exist wastes consumers' time and leads them to a dead end.

Fortunately, solving this mismatch can be much easier than fixing the situation where you add restrictions. In this case, what you can do is simply change the documentation so that it explains that a capability no longer exists whenever users try to open it.

Additionally, I'd also update the API reference so that, instead of removing a capability, I'd replace it with information explaining that the capability no longer exists. For users, it's much better to read a nice explanation than to receive a 404 whenever they open a link to a reference for a removed API operation.

Summary

Overall, the impact of introducing a breaking change on API documentation can't be neglected. Over time, if you don't update the documentation, it will become useless as it diverges from what the API actually offers. Updating your documentation whenever you introduce restrictions is the most complicated activity as you have to change the content to reflect the new reality. Whenever you remove a capability you can add a remark on the relevant parts of your documentation so users are aware of the situation. A technique I find useful to align changes with documentation is to maintain a list of documentation dependencies for each API operation.

---