I’ve heard a variety of bad advice (and some untruths!) regarding how to version your OpenAPI description lately. Rather than dig into those, instead I’ll share my opinion on how I like to version API descriptions in my own projects. Every API project is different, but perhaps there’s something here that can help your project too.

Version your API Descriptions

Let’s start with: please, please do use the version field, and update it from time to time. In OpenAPI, the version of the description is in the info.version field and the official documentation describes it as:

REQUIRED. The version of the OpenAPI document (which is distinct from the OpenAPI Specification version or the API implementation version).

To break this down, the documentation describes what the version field is, and also two things that it is not:

• it is the version of the OpenAPI document.
• it is not the version of OpenAPI specification being used (this is in the top-level openapi field).
• it is not the version of the API that it relates to (many descriptions cover multiple API versions, and may also change without the API changing).

So now we’ve cleared this up for OpenAPI, and pretty much everything here applies to AsyncAPI as well, let’s think about when the version should change.

When to update the API description’s version field

TL;DR when the API description changes, update the version field.

The whole point of a version field is so that I can tell if I have the most recent version of your API description, or which version something used. So if the two things aren’t the same, then probably their versions shouldn’t be the same either.

Some things that should probably cause a version change:

• a new endpoint was added to the API, or something was marked as deprecated
• the description was updated to include improved summaries, descriptions, tags or examples
• the description was restructured

Having a process that publishes a new OpenAPI description with an updated version is something you’ll want to be able to do easily and regularly, so make it painless to do.

A note on version formats: OpenAPI only recommends a string. Many organisations do use a SemVer approach, and this is well understood by technical audiences, but choose something that fits you. Take a leaf out of Stripe’s book and use dates for versions, for example. Whatever you choose, don’t get bogged down in what does or does not require a new release. Make new releases easy and aim for releasing too often rather than too infrequently!

This quick roundup on API versioning was the result of having this conversation several times over the last few weeks/months, with people all over the API ecosystem. We talk a lot about API versioning, but not nearly enough about API description versioning, so I wanted to share some thoughts and most of all encourage everyone to version their API descriptions (at all! With any sort of version!) and to update those version fields from time to time :)

Are there any organisations or APIs you’ve seen that do this particularly well (or badly, if you can be constructive about why it’s not working)? I’d be interested in seeing comments pointing to more examples of what you have spotted in the wild.