Request for API Version Chaining Feature

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

[ioggstream]

@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]

@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.