Communicating changes
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. API changelogs are an effective way to share with readers whatever changes you introduced since the previous version.
An API changelog is a document that’s usually a part of your documentation. It consists of a list of changes grouped by API version in reverse chronological order. Every time you create a new API version, you can automatically generate a diff that will be included in the changelog. You can generate the diff using the oasdiff tool you saw in action previously, or you can use any available commercial service. What’s important is that your changelog provides...
