Support API-wide version information

[dret]

This could be used to represent the version information of the described API. The current version field is oftentimes misunderstood and misused to represent the API version information. Having a registry-based extension could help as a quick fix, and new versions (3.2 and/or 4) will hopefully fix the current gap at the standards level.

The risk is that this could then be used in newer versions as well. I don't know how much this should be see as an argument against the proposal.

[handrews]

@dret We should see if we're going to put an apiVersion field in 3.2, and then if we put an x- version in the registry for <=3.1, we can make it clear that there is a migration path.

I just went to look for an issue for this to put into 3.2 and it looks like we don't actually have one? I really thought we did... I guess I'll just link to this issue for now (in discussion #4210).

[dret]

On 2024-11-21 17:09, Henry Andrews wrote: We should see if we're going to put an |api-version| field in 3.2, and then if we put an |x-| version in the registry for <=3.1, we can make it clear that there is a migration path.

I agree that it would be good to clearly indicate the potential versioning issues. I very much hope to see API version being supported in version beyond 3.1

I just went to look for an issue for this to put into 3.2 and it looks like we don't actually have one? I really thought we did... I guess I'll just link to this issue for now (in discussion #4210 <#4210>).

I thought so, too. Maybe we had the discussion in some other place, but I cannot remember.

[lornajane]

Agreed not to add this as an extension, let's discuss if we can add it as a formal field in 3.2 to describe an API description that applies to only one version of an API, for APIs where that makes sense.

[lornajane]

Related: OAI/sig-moonwalk#82

[dret]

All good for me. Let's discuss what the best path looks like. My goal is to be able to represent version information about an API in OpenAPI. Ideally there would be a recommendation how to do it in existing versions as well.

[handrews]

I've updated the title of this issue because my eyes just kept sliding over the x- as "this isn't relevant to me..."

I think we all know that there are many ways to version an API, and we're not going to figure out how to support all of them at once. Some are in-band, so there's really no need.

This is just to handle an out-of-band version field that applies to the entire API described by the OAD. I am sure someone will use it to duplicate version information already present in the Server Object URL, but we can't really prevent that from happening so I vote to just not worry about it- if people want to be redundant, they can deal with keeping things in sync. Or not.

---

The current version field is described as follows in 3.1.1:

REQUIRED. The version of the OpenAPI Document (which is distinct from the OpenAPI Specification version or the version of the API being described or the version of the OpenAPI Description).

Other fields in the Info Object say they apply to "the API", which we never explicitly define but probably ought to define as "all paths and webhooks described when treating this document as the entry document."

I think this means that any apiVersion field MUST apply only when the document is used as an entry document. apiVersion fields found in referenced documents MUST be ignored (this supports the use case where one API uses components from another API's entry document- not a use case I would recommend, but one that will no doubt happen).

[dret]

This all sounds good to me. There should be some model of how to decide what the "effective" API version is (if there are conflicting declarations), and using the entry document as an authoritative source sounds like a very reasonable model to me.

[lornajane]

I am not in favour of this change (but always happy to be outvoted). API descriptions should be able to describe multiple API versions, and I think adding a field to say that the API is at a single version could encourage a practice that isn't terrible but definitely isn't "best practice". I wrote more about this https://redocly.com/blog/communicate-api-changes https://lornajane.net/posts/2023/when-to-version-bump-your-openapi-description

Many users are confused about the version field. Adding another version field doesn't seem like the best user experience change we could make here.

[dret]

On 2025-02-23 07:23, Lorna Jane Mitchell wrote: I am not in favour of this change (but always happy to be outvoted). API descriptions should be able to describe multiple API versions, and I think adding a field to say that the API is at a single version could encourage a practice that isn't terrible but definitely isn't "best practice". I wrote more about this https://redocly.com/blog/communicate-api-changes <https://redocly.com/blog/communicate-api-changes> https://lornajane.net/posts/2023/when-to-version-bump-your-openapi-description <https://lornajane.net/posts/2023/when-to-version-bump-your-openapi-description> Many users are confused about the version field. Adding another version field doesn't seem like the best user experience change we could make here.

I am torn. I understand why adding a new version field on top of a frequently misunderstood version field may not sound ideal. On the other hand, the current field has semantics that few require and many misunderstand. Do you think there's another option how to make versioning better supported and understood?

[lornajane]

I believe that this is an API design and education issue as much as anything else. Sorry, I know it would be easier to add another field!!

[handrews]

@lornajane we actively support many API practices that I would not consider "good", because they exist in the wild. We've also said repeatedly that we want to take an even "bigger tent" approach to HTTP APIs in Moonwalk. Dictating API design by refusing to add this field seems to go against that. Why is this field an exception to that big tent approach?

[handrews]

@lornajane also, would adding more granular version support help? Is it just that you don't want to only add this field as an option?

[dret]

On 2025-02-23 12:44, Lorna Jane Mitchell wrote: I believe that this is an API design and education issue as much as anything else. Sorry, I know it would be easier to add another field!!

I absolutely agree that design and education are important hen it comes to API versioning, and I think providing more of these is one of our big goals for 2025. But even if design and education are there, representing the API version in a description to me still seems like a useful thing, as demonstrated by the many people who represent that version but in the wrong place.

[lornajane]

There are some really good points here, thinking about some of the alternative versioning practices and whether there is an option that is helpful (or at least not net-negative) for the majority?

[dret]

On 2025-02-23 12:53, Henry Andrews wrote: @lornajane <https://github.com/lornajane> also, would adding more granular version support help? Is it just that you don't want to /only/ add this field as an option?

Out of curiosity: What do you mean by "more granular"? My approach would be to support API version information, and to also produce content where we say that using semantic versioning is a good idea, and that investing into forward compatibility is a good idea as well.

[handrews]

@dret some APIs version the resource/endpoint rather than the whole API. There are various versioning strategies, not all of which put the version in the URL. It's been too long since I looked at current practices so I hesitate to try to come up with examples. But I'm sure some folks here have seen alternatives, and if we had a section on ways to capture different versioning strategies (instead of just one field and otherwise not mentioning versioning at all), it could be a good balance of education (promoting best practices) and accommodation (supporting APIs that have a baked-in versioning strategy and need to be described whether that is good or not).

[dret]

On 2025-02-24 09:33, Henry Andrews wrote: @dret <https://github.com/dret> some APIs version the resource/endpoint rather than the whole API. There are various versioning strategies, not all of which put the version in the URL. It's been too long since I looked at current practices so I hesitate to try to come up with examples. But I'm sure some folks here have seen alternatives, and if we had a section on ways to capture different versioning strategies (instead of just one field and otherwise not mentioning versioning at all), it could be a good balance of education (promoting best practices) and accommodation (supporting APIs that have a baked-in versioning strategy and need to be described whether that is good or not).

Now I see what you meant. Yes, I am sure there are many different practices out there and it may be impractical for us to accommodate all of them. But it seems like versioning at the API level and wanting that version to be part of the API description is not such a niche practice.