For developers and technical enthusiasts alike, few things are more exciting than a software release. While everyday users are accustomed to the typical “bug fixes and improvements,” expectations for changes within the developer community are much higher. Actively-maintained APIs are the foundation of numerous software products. It’s absolutely critical that technical teams make an informed decision before hitting “update” — as changes can markedly impact projects.

Software transparency is vital whether we’re dealing with open source, private, or partner APIs. This guide breaks down the importance of core changelog elements and why you should include them.

Version Numbers

Let’s start with the basics: versioning. Version numbers are easily-scannable progress indicators —whether of stable releases, nightly releases, or other development branches. For example, you might be familiar with Apple’s versioning approach for their software products. Major releases are assigned a full version number bump (say 14 to 15), significant updates within a major branch a partial bump (15.0 to 15.1), and incremental patches a minor bump (15.1 to 15.1.1).

Users have come to associate version numbers with an update’s overall scope or contents. A multitude of development teams have adopted this strategy for their APIs. It may be worth “telegraphing” the contents of your API updates based on version assignments. Conversely, one could emulate Facebook’s simplified Graph API approach, where most every update receives a full number bump. It’s important to choose a consistent numbering convention that developers will understand with relative ease.

In other words, your version numbers will reveal the following:

• Degree of change — including the size, overall packaging, and impact of a given update
• Order of release — or how an update falls in line with others chronologically
• Date of release — used by Google and others, a version number may directly indicate a release date

A version number can help convey the presence of features, security updates, and critical bug fixes. These patterns can help set user expectations. Accordingly, it’s useful to skim a version history on GitHub or on a vendor site when determining release frequencies — and how those align with update contents. Semantic numbering is essential in this quest.

Known Issues and Resolved Issues

Piggybacking off of expectations, it’s well-known that no software is perfect. Bugs and other issues often arise between builds; these can carry over to subsequent releases. For breaking changes especially, it’s important to note these and how they can impact functionality or compatibility.

Furthermore, it’s common for API developers to attach workarounds to persistent issues. These known issues can correspond to transitions — when moving from one technology to another, or replacing deprecated components. They can tell developers how to adjust their code accordingly to preserve functionality for end-users. These instructions help dependent programs run in a satisfactory manner until fixes eventually arrive. You might label each issue accordingly with ID numbers for tracking purposes.

Finally, we have resolved issues. These snippets in the changelog tell users what’s been fixed in the current build. Many such changes may have been long-awaited, and it’s crucial to showcase them for software developers. Noting any resolved issues is also critical for testing purposes. While a company can only replicate so many use cases and variables via internal testing, production environments can trigger all sorts of surprises. Developers can acknowledge any resolutions, and verify that they’re effective. They may then submit feedback accordingly to the API’s developer(s).

New Features

Everyone loves new features. They keep an API product fresh, exciting, and deliver on user requests. Software users often equate a product’s level of innovation with feature introductions — hence why remaining stagnant is detrimental to API adoption. Feature releases may fundamentally change how developers interact with APIs. Their effects may also be felt further down the chain by end-users.

Also, consider that some of your API features might not be outwardly apparent. Calling attention to them can aid in discovery and generally build buzz. Naturally, the depth and tone of your release notes can vary quite widely — from formal to playful. How you choose to highlight or “sell” new features can influence how much traction they gain.

Additionally, you might choose to note how specific POST, GET, PUT, PATCH, and DELETE calls interact with certain features (or how those interactions have evolved). We could easily tie this point back to known issues and workarounds, as well.

While some features may be completely unprecedented throughout an API’s lifecycle, others can completely replace those which previously existed. It’s important to mention this to set expectations and establish timelines. For example, Facebook mentions the following about the oEmbed feature within the Graph API v11.0 changelog:

The oEmbed product has been replaced with a new oEmbed Read feature. If you implemented the oEmbed product before June 8, 2021, you have until September 7, 2021 to complete App Review for the oEmbed Read feature. If you have not been approved for the oEmbed Read feature by September 7, 2021, your oEmbed implementations will fail to load.

When features are set to replace one another, some breaking changes can occur at a later date (if not immediately). Developers who care about their users should note any conditions or transitions in plain language — as not to cause confusion or unwelcome surprise.

Deprecations

Lastly, it’s common that code, methodologies, and features are retired throughout an API’s lifecycle. This occurs as products and user behaviors evolve; it’s indicative of ongoing development. A deprecation effectively signals an API component’s end of life. All developers should explain how major deprecations will impact configurations, code execution, HTTP requests, and more. Leaving developers in the dark will only cause problems and frustration.

It’s common to couple deprecations with upgrade recommendations, since newer protocols will now exist in their places. These may happen automatically during an update. However, the onus may be on the developer to adjust their API code and preserve integrations. Either way, your API users must have a clear path forward to avoid crippling issues. This may exist explicitly within the changelog or live within the API itself. For example, if one’s program recognizes a deprecated component, your API could trigger an alert for your users to keep them abreast of the situation.

As with known issues, some deprecations also have their own workarounds.