Skip to content

Request for API Version Chaining Feature #1397

@dberlind

Description

@dberlind

Hey all, after discussions with Marsh at API Strat, I'm putting forth a feature request that allows for better API version discovery. It's basically triplets (aka hypermedia) for versions.

Today, the spec allows for notation of the current version. However, humans and machines have no way of knowing if, when "interrogating" an particular OAS file, if you're looking at the most current version, if there's a previous version, or if there's a next version. It'd be great if machines/humans could see where in the chain of versions, they are when looking at a specific spec.

So,

info: 
   version:                  2.4.1  (this version)
   previousVersion:  <uri to openapi spec for previous version>
   nextVersion:          <uri to openapi spec for next version>

pretty simple. from there, machines/humans can take care of the rest.

Background here is that tooling should be able to monitor a spec file to spot changes to the API. However, unless it's a super minor change, then those changes trigger a new version and subsequently, those changes are reflected in a new spec file (as opposed to the existing spec file). But currently, there's no way for machines/humans to determine from a current spec file if another spec file exists.

Extra credit might be another field to give some additional status as to the production-level of the current spec file. For example:

info: 
   version:                  2.4.1  (this version)
   previousVersion:  <uri to openapi spec for previous version>
   nextVersion:          <uri to openapi spec for next version> 
   productionStatus: Pre-Release

This might be more difficult as its effectiveness would require standard vocabulary which might trigger a difficult debate. But, if there's interest in this feature, I do have suggested vocabulary that spans everything from pre-release to deactivated.

Thank you.

David Berlind
ProgrammableWeb

Activity

earth2marsh

earth2marsh commented on Dec 8, 2017

@earth2marsh
Member

version can be tricky… in this case it's the version of the specification-document itself, not the implementation.

An alternative might be to publish all specs under the same directory whose contents could be queried, not unlike how libraries like jQuery are sometimes made available (example), and possibly with an HTML index page to help orient people. If the provider used a versioning approach like semver, then the latest should be self-evident.

dberlind

dberlind commented on Dec 12, 2017

@dberlind
Author
earth2marsh

earth2marsh commented on Dec 12, 2017

@earth2marsh
Member

I'm not disagreeing that chaining versions might be useful in tools like Swagger UI—just observing that there are conventions that providers could adopt in order to work around the lack of version chaining support in the spec itself. I think there is a case to be made for adding this to the spec, we just need to hear from more people that it's a top priority.

darrelmiller

darrelmiller commented on Dec 15, 2017

@darrelmiller
Member

Discovery of API Versions is something that the TSC (meeting 2017-12-15) feels is out of scope for the OAS, but part of the bigger topic of API discovery. There is an OAI Scope Working group that is planning to discuss the broadening of the scope of the OAI to potentially include this topic.

CamyDee

CamyDee commented on Jan 4, 2018

@CamyDee

As an alternative to the previously mentioned approaches, there may be greater value in specifying "operational versioning", which others may find more in-scope to OAS as well. The idea here is that APIs don't necessarily change all at once, but a little at a time, and more at the operational level than the API level. Individual operations could be versioned, still requiring unique operationIds and paths, but associated to one another by a common identifier and a version number indicating which is newer. There are already 3rd party extension mechanisms taking this approach in order to manage the lifetime of an API as it continues to grow and develop over time. The result is a somewhat larger OAS spec, but a more complete one, and something that can be easily processed by many different means - automated or otherwise. There are already pieces of this in place - such as the deprecated property, but no way to specify "here's the new version you should be using instead!".

dberlind

dberlind commented on Jan 4, 2018

@dberlind
Author

Thanks @darrelmiller and @CamyDee. I can't imagine any machine or human reading an OAS spec and not wanting/needing to know if it's the current version or if there might be a newer, production version. IMHO, the spec file is the most obvious place to share this information. The level of difficulty of implementation seems trivial. I'm still interested to know if there's an actual occurrence in the wild where the version of the spec file is not the same as the version of the API it represents.

handrews

handrews commented on Jan 5, 2018

@handrews
Member

@dberlind I can't vouch for an actual in-the-wild OpenAPI spec vs API version mismatch, but if I made an error in the spec I would release a new spec version without changing the API version. It's a bug fix of the spec, not a bug fix to the API.

dberlind

dberlind commented on Jan 5, 2018

@dberlind
Author

@handrews thanks for that. I believe that this may surface a weakness in the current spec. Who, for example, would want to be reading a spec file, and not know what version of the API it applies to? The version number may not be readily apparent from the base URL. Going back to my original proposal, perhaps I the syntax should be different as in:

info:
   specVersion:                      2.4.1-b
   thisApiVersion:                  2.4.1  (this version)
   previousApiVersion:          <uri to openapi spec for previous version>
   nextApiVersion:                 <uri to openapi spec for next version> 
   productionStatus:              Pre-Release```
  
ioggstream

ioggstream commented on Jul 15, 2019

@ioggstream
Contributor

@dberlind I suggest to delegate the maturity status to a lifecycle parameter. Ideas?

info:
  version: 2.4.1
  lifecycle:
    maturity: pre-release  # or whatever, just define an enum
    links:
    - rel: prev
      url: https://prev-oas-spec
    - rel: next
      url: https://next-oas-spec

dberlind

dberlind commented on Jul 15, 2019

@dberlind
Author

@loggstream, quite frankly, it can go into any parameter as long as it is in there. The fact that this suggestion was refused as being out-of-scope for OAS is a travesty. API versioning is a major issue. Among the major API providers, we at ProgrammableWeb have observed with interest some evolving maturity in how API versioning is done so as to maintain some degree of continuity with developers. To suggest that version pointers are out of scope (when the spec already allows for the current version #) destroys one of the key objectives of machine-based introspection. Furthermore, to suggest it belongs in some other machine readable file as I believe was suggested here just highlights a key weakness in the REST architectural style vs. up and comers like gRPC and GraphQL (both of which involve "in-band" introspection vs. hunting down some file. Done right, all APIs should have some standard referral to the description and each description should be one link in a chain of descriptions. Anything else is a MAJOR developer inconvenience and my understanding having followed APIs and their predecessors closely for three decades is that developer empathy and experience is a #1 priority.

2 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

    OAI-scopemetadatatags, info, license, contact, markdown usage, etc.versioningdescribing versions of APIs/endpoints/operations

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

      Development

      No branches or pull requests

        Participants

        @earth2marsh@darrelmiller@ioggstream@handrews@CamyDee

        Issue actions

          Request for API Version Chaining Feature · Issue #1397 · OAI/OpenAPI-Specification