Skip to content

Support API-wide version information #4212

@dret

Description

@dret
Contributor

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.

Activity

added
metadatatags, info, license, contact, markdown usage, etc.
registriesRelated to any or all spec.openapis.org-hosted registries
on Nov 21, 2024
handrews

handrews commented on Nov 21, 2024

@handrews
Member

@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

dret commented on Nov 21, 2024

@dret
ContributorAuthor
added this to the v3.2.0 milestone on Nov 21, 2024
lornajane

lornajane commented on Nov 28, 2024

@lornajane
Contributor

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

lornajane commented on Nov 28, 2024

@lornajane
Contributor
dret

dret commented on Nov 29, 2024

@dret
ContributorAuthor

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.

changed the title [-]Add x-api-version to extension registry[/-] [+]Support API-wide version information[/+] on Jan 25, 2025
handrews

handrews commented on Jan 25, 2025

@handrews
Member

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

dret commented on Jan 27, 2025

@dret
ContributorAuthor

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

lornajane commented on Feb 23, 2025

@lornajane
Contributor

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

dret commented on Feb 23, 2025

@dret
ContributorAuthor
lornajane

lornajane commented on Feb 23, 2025

@lornajane
Contributor

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!!

15 remaining items

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    metadatatags, info, license, contact, markdown usage, etc.registriesRelated to any or all spec.openapis.org-hosted registriesversioningdescribing versions of APIs/endpoints/operations

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

      Development

      No branches or pull requests

        Participants

        @lornajane@dret@handrews@miqui

        Issue actions

          Support API-wide version information · Issue #4212 · OAI/OpenAPI-Specification