Skip to content

Release Notes

Requirement

  • Release notes must accompany each major and minor release, along with an updated OpenAPI specification (OAS).

Guidance

  • It's optional but recommended to publish release notes for patch versions.

By virtue of your code being an interface that other software relies upon, it is important to publish release notes when the API changes.

Release notes are required if an API changes in a way that could affect a consumer's capabilities. This is regardless of whether the change is within a major, minor, or patch release (Major.Minor.Patch). As discussed in the versioning section, examples of semantic versioning minor changes include an additional endpoint, an additional response property, or a new optional query parameter. These are examples of non-breaking changes but changes a consumer is typically interested in knowing about. Therefore, the OpenAPI specification (OAS) must be updated AND release notes must be published to highlight the new functionality.

API teams may optionally publish releases for changes internal to the API which are abstracted away from the end user. This is almost always a patch change. For example, iPhone security updates do not affect the UI and are released - with a one-sentence release note - as a patch version, e.g., iOS 14.8.1.

A second example of when release notes are required is when a release causes a change in behavior in the underlying system. i.e., an endpoint with the same contract as before, when now called, has a different effect on its system or upstream systems.

The final example of release notes being required is when a new major version of your API is released. This is typically a breaking change for consumers and they will eventually be required to migrate from the prior major version to the latest major version. Help your consumers plan ahead by telling them about this as early as possible.

In summary, API teams must publish release notes and an updated OAS when the API's interface changes or the system's behavior changes. API teams may optionally publish release notes when a change is internal and does not update the interface or cause new side effects to the underlying system's data.

What should the release note contain?

Release notes should contain the release date, a summary of what has changed, and optionally the release number.

It is best practice to always publish a release note with every change to your API, even if the changes should not affect the consumers of the API.

Consider the perspective of the consumers using your API, from both the developers' and product managers' point of view. The release note is to increase awareness of changes being made and, is an important first source of information when debugging and troubleshooting a problem when the consumer's application using your API starts to behave differently. It also shares behavior changes that could affect how consumers interact with your API.

This is not an all-inclusive list, but certainly mention:

  • a new endpoint
  • a new parameter or property that is allowed
  • a change in a value that is accepted
  • additional fields in a response
  • new headers that are returned
  • updates that shouldn't have any effect, but might
  • documentation changes, such as improving examples
  • deprecated fields in the response and alternatives that can be used
  • deprecated endpoints and alternatives that can be used

Example non-breaking endpoint change

**September 26, 2024** ( Version 1.5.0 )

Added an optional POST parameter for middle name on the /registrations endpoint.

Example bugfix change

**September 19, 2024** ( Version 1.4.0 )

Fixed the /registrations endpoint to accept the single quote character (') in the first name and last name fields so that names such as O'Malley will now be accepted.

Example patch release change not affecting consumers

**September 12, 2024** ( Version 1.3.1 )

Updated several third-party libraries to enhance performance, security, and functionality. No behavior changes should be noticed.

Example minor release change not affecting consumers

September 5, 2024 ( Version 1.3.0 )

Improved the underlying data structures, no behavior changes should be noticed.

Example deprecation of an endpoint

August 15, 2024 ( Version 1.2.0 )

Deprecated the POST /register endpoint. Please move to using POST /registrations instead. The deprecated endpoint is scheduled for complete removal in approximately one year (August, 2025).