OAS3 specified Service Versioning

Question

We are currently specifying a new REST service API using OpenAPI Service Specification v3 OAS3. Because of a bunch of different reasons we need/want to make the service API versioned from the start (this is mandated by factors not within our control).

The versioning scheme we would like to use is URL path versioning - i.e. something along the lines of .../v1/ourservice.

Does someone know how such a versioning scheme can be tracked in OAS3 specification?

So far I have only seen a global version attribute in OAS3 - but nothing that would allow us to easily specify multiple versions in one YAML file (or is this the wrong way to go about this in the first place?).

FYI, we are planning to use a top-down approach, i.e. define our service API as OAS3 YAML and then proceed to generate server and/client side code from that using Swagger generator.

Finnell

Answer 1

version in the OpenAPI document refers to the version of the document not the version of the API.

From the spec:

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

So, there are unfortunately three versions you'll need to be concerned with. Here's what those look like:

• specification version (Must be one of those defined at https://github.com/OAI/OpenAPI-Specification)
  Example:

oepnapi: 3.0.2

• The document version. I usually expose this as the git SHA1 hash for an auto-generated doc.
  Example (see version):

  title: Sample Pet Store App
description: This is a sample server for a pet store.
termsOfService: http://example.com/terms/
contact:
  name: API Support
  url: http://www.example.com/support
  email: [email protected]
license:
  name: Apache 2.0
  url: https://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1

• The API version.
  Some people consider path versioning controversial, but many of us (myself included) have to do this for a number of different reasons outside of our control. A common way to achieve this in all specification versions is to define the path version in baseUrl. For instance, your base URL could be /nested/v1 or simply /v1. This unfortunately would only cover the v1 approach.

OAS3 supports server variable templating for more complex API version configurations. This looks to be exactly what you're looking for. However, these variables aren't fully supported in all generators in OpenAPI Generator, yet. If you have specific generator(s) in mind, please open an issue for these as initial support appears to only exist in Ruby, PHP, python and JavaScript ES6 client generators.

Ankeny

Thanks for this great response! I have a follow up question to this one - what would be the best practice for specifying planned minor versions with new features of the API which are downward compatible but will be deployed at a time T in the future and for which we want to document how the slightly extended version of the API will look like at time T for clients using the API? – Ninette

@Ninette that's difficult to say, really. For OpenAPI Generator, we have two SaaS generator APIs, one at api.openapi-generator.tech which targets the API of the last release, one at api-latest-master.openapi-generator.tech targeting master. If we made backward compatible changes in master, a user could generate against the doc from the latter server. – Ankeny

Thanks a lot for your response! I was just wondering if there was maybe a solution to just point out minor changes like adding additional parameters or additional methods by keeping full downward compatibility and then showing users of an API which additional parameters/methods they can expect in an upcoming future release... – Ninette

The spec doesn't really prescribe API versioning strategies. If you used the OAS 3.0 server variables, and your strategy included a version variable, that might work but you wouldn't be able to differentiate breaking vs non-breaking changes with just a variable. You could maybe use summaries in a specific API to call out upcoming new features. Apigee used to have some really good whitepapers on API versioning, but they're probably either gone or turned terrible now after the merger to Google Cloud. You could search if those whitepapers are still available. – Ankeny