Request for API Version Chaining Feature

[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

[earth2marsh]

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]

I was not aware that the version in the spec referred only to the version of the document itself and not the version of the API. Do you think there are any real-world instances where the two are out of lockstep? It just seems like that would create so much confusion. I mean, imagine that you had two versions of an API in production (versions 2.4 and 3.0) but that the versions for each in the corresponding OAS description were 9.6 and 11.1? There would be a lot of head scratching. I understand that the spec *allows* for that possibility. But, in reality, is that really the practice or are the two (the doc version and the API version) kept in sync as a defacto approach? Regarding directories, semver, etc....IMHO, those ideas venture too far away from spec or standard and more towards best practice which means that, in all practicality, we will not see any critical mass let alone wide-spread adoption. There are plenty of other suggested best practices for APIs which, as beneficial as they may be, have hardly taken root as a defacto. I still think the OAS desc file is the best place. And, even if it only "officially" represents the version of the document and not the API, it would still be useful to have. That way, the versions of the docs can be chained together and if the doc versions and API versions happen to be in sync, then all the better. Looking forward to a response.

…

On Fri, Dec 8, 2017 at 11:02 AM, Marsh Gardiner ***@***.***> wrote: version can be tricky… in this case it's the version of the specification-document itself <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#info-object>, 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) <https://developers.google.com/speed/libraries/#jquery>, 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. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#1397 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AGVduhmFB0ZdUE22nHXiqTuUQUa7yuaOks5s-V2SgaJpZM4QQB6c> .

[earth2marsh]

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]

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]

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]

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]

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

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

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