Replies: 6 comments 7 replies
-
|
In my experience this way of versioning is a very common pattern. I've worked in a number of places where the organization aims to version Path Items or Operations, and therefore sees a version at That could be rationalise into a MO, however, rather than being dichotomous i.e.:
You could therefore have something like (informative not normative, to make the point): /pets:
version: 1.0.0
get:
...Or even: /pets:
get:
version: 1.0.0
...Anecdotally in said organisations people reacted in horror to the idea of versioning using I personally feel like a multi-faceted versioning system is therefore something worth solving for in Moonwalk. I am 100% sure that there are folks in the community who'll tell me this is wrong and APIs should be versioned in one place all the time, but on the other side of the fence there are thousands of organisations who just don't want to do it that way. We should facilitate them rather than provide a dictate on best practice. |
Beta Was this translation helpful? Give feedback.
-
|
Thanks, @SensibleWood !
Isn't this already how it is defined? |
Beta Was this translation helpful? Give feedback.
-
|
Yes in the exact words of the standard but for a good chunk of people the API version and the OpenAPI document are one in same. They are closely coupled because the docunent version is the most practical way of communicating the API version. |
Beta Was this translation helpful? Give feedback.
-
|
@handrews @SensibleWood Supporting operation-level versioning in addition to API-level versioning makes sense. Such as security can be now defined on global level or an operation level (overriding the top level), the versioning could be as well. Though, once we allow operation-level versioning, we should be able to cover multiple versions of the operation in a single definition. Also, allowing just the single version of the API declared compatibility (implicit relations) between operations. Once we allow operation-level versioning, new relations between operation versions may arise (e.g., if you created the resource with the v4 operation, you need to update it with v5 operation or higher). The meaning of the top level versioning has to be clear, whether it means the version of the definition (document), or the API contract. Up to now it was both at the same time. If we make the API-level contract version optional, I'd suggest to introduce the document version in addition to the API-level contract version. Though, there's a risk of misunderstanding. Even today, people often confuse the API contract version with the deployment component (release) version. |
Beta Was this translation helpful? Give feedback.
-
|
Agreed. If the "multiple versions" design manifests itself in the Moonwalk specification then there should be clear guidance how to interpret what is present in a given OpenAPI document |
Beta Was this translation helpful? Give feedback.
-
|
We have actually had several requests around things like operation-level versioning. |
Beta Was this translation helpful? Give feedback.
-
|
Having mullificated on this for a bit longer, it strikes me that the one property aimed at versioning in specification as it stands is quite limiting for both API providers and consumers alike. Thinking more about my experiences in different organisations leads to me think we could provide for offering more information in the specification, with enough optionality to allow providers to make sensible choices on what they publish. For example, here are some things that in my experience do work or could work and be provided alongside each other:
Therefore you could end up with - and largely waxing lyrical here, but just tossing ideas out - a openapi: 4.0.0
info:
versions:
document: 1.0.30 # The document version, patched many times as only descriptions and summaries changed
api: 1.0.0 # This document describes the API at 1.0.0
scm: f2f4ab52e1dd184b75dcf9d18d3efd4feff41ee4 # The commit in GitOr if you are into versioning by Path Item but wanted to only publish one OpenAPI document to rule them all: openapi: 4.0.0
info:
versions:
document: 1.1.0 # The document has changed and shows a new Path Item that is optional
paths:
/apples:
version: 1.0.0
get:
...
/bananas:
version: 1.2.0
get:
...To summarise: The specification could provide more information on versioning, in a number of useful ways. IMHO I think there is enough precedent in the API ecosystem to design for this kind of approach. It would also prevent the need for Specification Extensions to provide for this kind of stuff. |
Beta Was this translation helpful? Give feedback.
-
|
As a consumer of the API, if I see different versions of the resources I'd need to understand how to address the right version. There are multiple approaches:
I believe we need to enable such clarification in Moonwalk as well, both for people and machines. |
Beta Was this translation helpful? Give feedback.
-
|
I agree. It would be useful if there was joined-up design on stating a given version in the document and address a given version by one of the mean described above, so that the 2 things could be described "in sync" in a given OpenAPI document. |
Beta Was this translation helpful? Give feedback.
-
|
For practical purposes, from a client developer perspective, how would it be different from having two documents, one on each server, describing the version it supports? |
Beta Was this translation helpful? Give feedback.
-
|
Is versioning supposed to be used by client libraries, and if so, how? If one server can support multiple versions, it needs a means of communicating a version by path or query parameter, or a header. This is already supported, isn't it? Otherwise what's the point, other than concealing the fact that some API is unstable? |
Beta Was this translation helpful? Give feedback.
-
This whole thread is about communicating a version of the API in the OpenAPI description document. Regardless of the ways you list OpenAPI needs to say "I am version x and this is how that information is described". Potentially that could be made better in Moonwalk, with more formal support for documenting it. The myriad of ways of addressing a version at runtime still exist regardless. |
Beta Was this translation helpful? Give feedback.
-
|
What I meant was, as long as your server supports one version, the version can be implied. If however the server supports more than one version, it must be communicated as part of the HTTP exchange (header or else), making any separate version property redundant. |
Beta Was this translation helpful? Give feedback.
-
In today's call the idea came up that an API shape should only represent a single "version" of an "API." I spoke strongly against this on the grounds that not all APIs use coarse-grained versioning that would be compatible with such a restriction.
I'm going to use an example from an API that was never publicly available, but please understand that I am not suggesting that Moonwalk do anything in particular to support this approach. No such special features are needed. All I'm doing here is demonstrating that other approaches to API change are possible and have been attempted. By the "Big Tent" principle, this should be sufficient to require not encoding API-level versioning into the OAS.
If we want to have some "best practices" around what to do with API-granularity versioning, that's fine, but please let's not assume all APIs work that way. Even if the majority do, we want to leave room for innovation and change.
The following is not exactly accurate as it's been quite a few years, and I'm glossing over irrelevant details. But it's accurate enough. Because of acquisitions and changes in direction, this was never deployed, but it was the official plan at one point.
The counter-example I had in mind was for a network appliance, so every deployed appliance hosted an API based on the product version. It was common for a customer to have different appliances on different versions. For various reasons, mostly outside of engineering control, nearly every significant product release had at least one incompatible change to at least one API endpoint. Therefore nearly every revision of the API was a new major version. No one was happy with this.
However, it was rare for more than just one or two endpoints (or resource representations) to change in an incompatible way at once. And often, the change would be in a relatively obscure area that only a handful of customers cared about. This is part of why such "breaking" changes were acceptable. The problem was that the major version change impacted everyone, and even if they didn't really need to change anything, it caused customers to think the whole interface was unstable.
So the plan was to version at the resource representation granularity. A lot of resourced just didn't change much. A few more changed in backwards-compatible ways. And then just a few would tend to be incompatible. But they didn't always clump the same way, so we couldn't just split it into 2 APIs - a stable one and an unstable.
I've forgotten the exact details, but part of it took inspiration from Stripe's date-based versioning, where "your" version was determined by the first time you call the API. Because of the nature of the product, there was always an IT person or team assigned as an admin, so part of the software upgrade process would have checked the logs and reported on what resources were actually used that changed, and provide options on how to handle it.
There were tricky details to work through in that change process, and I don't recall all of the decisions. I do recall that I sold folks on it as do-able. Mostly because API-level versioning was such a pain point, and it was easy to prove that it was actually wrong for most customers with most updates. That was enough motivation to work out a lower-customer-impact change management policy.
Beta Was this translation helpful? Give feedback.
All reactions