Documenting API Changes
Documenting API Changes
Should you document all your API changes?
Every change you introduce to your API will surely affect someone. It doesn't matter how impactful you consider the change to be. What consumers care the most about is their integration with your API works flawlessly over time. Will you be able to keep consumers untroubled by documenting all your API changes?
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.
APIs can change all the time. Changes can happen for different reasons. Some common causes for introducing a change include fixing something that's not working as it should, introducing a new feature, and deprecating an operation you no longer wish to support.
API stakeholders can identify changes reactively or proactively. Reactive identification of changes informs consumers whenever the API isn't behaving as previously. Consumers can reactively recognize a change by running API integration tests. Whenever a test fails it means the previous behavior has changed. This method gives consumers first-hand knowledge of your latest API changes. However, knowing when something changes after the fact isn't ideal for most consumers.
Consumers prefer to know about API changes before they happen. Or, at least, when they're about to be introduced. Also, the most valuable information about a change isn't the change itself. Instead, as a consumer, you want to know the reasoning behind the change and what you need to do to keep your integration running without issues. The worst thing that can happen to API consumers is seeing the integration code they built rendered useless because of a breaking change.
Generally speaking, breaking changes are the worst kind. In other articles, I covered how breaking changes affect API consumption and also how they can make parts of your documentation useless. Many people care only about breaking changes. I, on the other hand, like to think of any change as an opportunity to communicate with API consumers. As I wrote in "Building an API Product," having an API Changelog is an effective way to share any API changes with consumers.
Sharing information about API changes with consumers doesn’t have to feel like you’re sending bad news. Many changes are expected by consumers. Some of these changes are even the result of feature requests that came from consumers. The best way to create the habit of communicating changes whenever you deploy a new API version is by maintaining and updating a changelog.
Having the habit of communicating changes increases the trust consumers have in your API. In general, people try to avoid relationships where the only existing communication is about bad news. With an API Changelog, you create an open channel that consumers can consult whenever they want to know about the latest updates. Any consumer—or other API stakeholder—can easily browse through a chronological list of changes and review their potential impact on existing integrations. While a changelog is a powerful tool, using existing documentation as a way to communicate changes is an effective supplement.
Adding information related to API updates to your documentation is not as hard as it sounds. Every time you're documenting an API feature, e.g., an operation, you can add information related to when you first introduced it and what its latest update was. Similarly, when you deprecate a feature you can still keep it as part of the documentation but add information about the deprecation. When consumers see this information they're able to have a better understanding of the context behind each feature.
As an example, consider a feature called "Payments" and an operation that lets consumers create a payment, e.g., POST /payments. The documentation for this operation would explain how to use it, show the expected POST payload, and even provide an example using your favorite programming language. Additionally, you could also add information related to the changes that occurred in the operation. The information can be as simple as:
Introduced on April 1, 2020. Last updated on April 1, 2024.
A great addition to this information is a link to the changelog of that particular operation. The information on the changelog has to be more complete, though. For every change that happens in the operation, there's a list of helpful items you can add. The first one is a human-friendly description of the change. The description should identify what the change is, why it happened, and what consumers can do to update their integration if needed. The second item is related to the category of the change. Here you can share if you consider this change a fix, an increment, or a deprecation. Then you can also signal if you consider this a breaking change. With all this information consumers will be able to understand the history of the operation they're interested in and decide what to do next with their integrations.
Overall, API changes are definitely a reality you can't escape from. By documenting every change and being transparent to consumers you increase their trust and improve the quality of your API. I consider a well-documented API changelog followed by actionable documentation on how to update integrations a must-have for any API.