Service versioning in OpenAPI

Question

We are about to implement a service API for my client that consists of a number of services, lets say ServiceA, ServiceB and ServiceC. Each service can over time (independantly) introduce new versions, while the old versions still exist. So we might have:

• ServiceA v1
• ServiceA v2
• ServiceB v1
• ServiceC v1
• ServiceC v2
• ServiceC v3

We are required to document this API using OpenAPI. I'm not too familiar with OpenAPI, but as far as I can see you typically version the entire API, not separate services.

How would one typically document such versioning using OpenAPI? Personally I see two options, but I am very likely missing something:

1. Add each version of the same service as separate services in the documentation (but that causes a bloated API over time with a lot of services)
2. Increase all the services versions and the entire API's version everytime a single service changes version so there's always a version 1, 2 and 3 of each service, even if some of them are identical (but that introduces a lot of unneccesary service versions).

Any input would be much appreciated.

Answer 1

Maybe a little late, but consider this point of view.

If the service API is implemented by a compact component, then the API should also be compact. The consumer of your service is not interested into your versioning policies more than to the extend of backwards compatibility violations and/or new feature addition.

It is absolutely out of scope to require the consumer to know all your version numbers for individual services. He does not want to know it, he wants a complete, compact package.

If you services have little in common, your best solution may be individual OpenAPI documents with tailored versions. The point is - you will not block development of your components by unrelated customers/consumers relying on the remaining services, and you will not bother the customers with zero-change version changes for their field of interest.

On the other hand, you may as well keep a version number that is separate from the endpoints.

Something like this:

openapi: 3.1.0
info:
  version: 2.0
  servers:
  - url: http://somewhere.com/v2
paths:
  /some-action:
    ...

instead of

openapi: 3.1.0
info:
  version: 2.0
  servers:
  - url: http://somewhere.com
paths:
  /v2/some-action:
    ...

Now, your clients are expected to configure the address of your service http://somewhere.com/v2 and use it for all services, A, B, C. Once you decide to release a new major version /v3 which breaks compatibility on service A, and brings new features to B, C, and possibly new D:

• You may keep http://somewhere.com/v2 running with old service component version for existing customers.
• The API may inform them in some way about using deprecated endpoint
• You may keep both API specs published in your dev documentation tool.
• Customers only using A, B may just swap http://somewhere.com/v2 for http://somewhere.com/v3 on a resource URI level and not change/rebuild any code.
• Customers using A may keep using old version, and design a slow shift towards /v3 by addressing ONLY code working with A
• New customers may start off by using current LIVE version, having a compact API. You definitely do not want to force them to learn which is the current latest version for each service separately, they want to encapsulate the versioning inside server as well. Also, they are free to use D.