Add `info.lifecycle` with maturity/lifecycle informations.

[ioggstream]

The proposal

A LifeCycle object to describe the API lifecycle, eg:

info:
  lifecycle:
    maturity: published   # or deprecated,  retired, ...
    published_at: 2019-01-01
    deprecated_at: 2022-01-01
    retired_at: 2022-06-01

Data related to other version may be specified eg. via link relations

    links:
    - rel: prev
      url: https://prev-oas-spec
    - rel: next
      url: https://next-oas-spec

Benefits

Automatic discovery of API status.

Considerations

• http://apisjson.org/ seems not maintained anymore
• we already have deprecation informations in operations
• lifecycle could contain further informations related to eg. versioning (link to previous spec versions)

Related to

#8

[ioggstream]

@dberlind @dret further consideration on how to improve this feature request are very welcome!

[dberlind]

@loggstream, based on our observations over the last 13+ YEARS of cataloguing APIs and there version, we've made a few observations about API status across API providers and have, for the most part, narrowed a current version's status down to one of the following (trying to keep it very simple):

1. Pre-Release
2. Recommended (active, supported)
3. Active (supported, scheduled for retirement)
4. Retired (still active, but unsupported and scheduled for deactivation)
5. Deactivated

Note that the term "deprecated" is not included here. In our research, we have found that there are different meanings for "deprecated." And so, in our parlance, the verb "deprecate" is not included as an official term but essentially means the advancement of an API from levels 2-4 to some following level. For example, when you change an API's status from level 2 to 3, that is an act of deprecation. Same would go for changing an API's status from 3-5 (though we wouldn't suggest that API providers ever make this leap.

For extra credit, when a status indicates some forthcoming deprecation (ie: the way level 3 indicates that retirement is coming), you could include a date field for when that change is planned to take place.

By the way, one other key use of this "version graph" would be the automation of regression testing such that breaking changes between versions are sussed out. This advantage to my proposal was raised by Alexander Pournelle (I don't have his Github ID yet, but will add it when I hear from him next).

[dberlind]

Also, for the sake of "holy cow," just thought I'd point out that the related issue (#1397) is just a change in the order of same digits of this issue's number. Might be time to play the lottery.

[dret]

On 2019-07-15 21:54, dberlind wrote: 1. Pre-Release 2. Recommended (active, supported) 3. Active (supported, scheduled for retirement) 4. Retired (still active, but unsupported and scheduled for deactivation) 5. Deactivated

neat. this is the same model that we use in the CAM book. we just present it as an example (and encourage API landscapers to come up up with phases that work best for them), but it seems like it is a popular choice.

For extra credit, when a status indicates some forthcoming deprecation (ie: the way level 3 indicates that retirement is coming), you could include a date field for when that change is planned to take place.

this is a nice parallel to the sunset and deprecation HTTP header fields (https://goodapi.co/insights/deprecation-and-sunsetting) that carry date information.

[dberlind]

Thanks @dret. The phraseology is an outcome of a years-long informal study of public API provisioning behavior. This is not necessarily the exact phraseology all API providers use. But, I believe it to be a very practical, common sense based, easily understood standard that applies to 99 percent of the behavior we've observed.

[earth2marsh]

At one point we had hoped that APIs.json would complement OpenAPI, which allowed us to avoid tackling this question head-on. However, given the time elapsed, I agree it may be worth reconsidering. Yet it also makes me wonder about some things...

For example, I think of a spec as a snapshot in time of the interface for a service that is represented with a consumer-oriented contract (only because the apparent surface may vary by consumer). The spec might have inaccuracies, so it may change independently of the service itself. If we used a word like published, would it distinguish between the spec publishing date/time or the service it describes? What if you have a spec that describes a pre-released iteration of a minor update to a production service? Myself, I consider a spec to be an artifact of the overall API lifecycle itself, as well as having a lifecycle itself. Words begin to spin...

One starting point might be to consider whether someone were reading an OpenAPI spec, how might they know whether that spec was the latest version, and if not the latest, how to locate what superseded it? For example, it might be a copy. Should we consider a URL to the "canonical" spec? If it were the latest version, might it be useful to declare it as head or latest? What about the next minor vs major version of the service?

At the risk of rambling further, I'd suggest that before we add support for lifecycle declarations (which may well be a good addition to OpenAPI), we should first capture clearly which problems we hope to solve. Only after might we know whether the proposal solves them elegantly enough! For example:

1. As a potential API consumer, I want to understand the stability of a service so that I don't waste time coding to an interface that is likely to change (alpha) or may disappear (deprecation/retirement).
2. As a developer of an application, I want to be able to understand what may have changed in an API that might explain a new bug that I've observed.

[ioggstream]

@earth2marsh

before we add support for lifecycle declarations (which may well be a good addition to OpenAPI), we should first capture clearly which problems we hope to solve.
Only after might we know whether the proposal solves them elegantly enough

Ok. We could use a proposal template to make a due diligence for the proposal.

1- As a potential API consumer, I want to understand the stability of a service so that I don't waste time coding to an interface that is likely to change (alpha) or may disappear (deprecation/retirement).

Ok

2- As a developer of an application, I want to be able to understand what may have changed in an API that might explain a new bug that I've observed.

As a manager of an API Ecosystem, I want to establish and enforce quality standards for APIs that
mandates an API provider to specify the lifecycle of their APIs.

As an API consumer I want to be alerted when API life events. Providing those informations in the specs enables the creation of automatic alarms for those changes.

[ioggstream]

This comment just maps @dberlind maturity model to the CAM one

  1. Create   -> Pre-Release 
  2. Publish  -> Recommended (active, supported)
  3. Realize  -> Active (supported, scheduled for retirement)
  4. Maintain -> Retired (still active, but unsupported and scheduled for deactivation)
  5. Retire   -> Deactivated

[dberlind]

It's good to see that the CAM model agrees that 5 stages pretty much covers all possibilities. No reason to over complicate things.

…

On Fri, May 8, 2020 at 11:49 AM Roberto Polli ***@***.***> wrote: This comment just maps @dberlind <https://github.com/dberlind> maturity model to the CAM one 1. Create -> Pre-Release 2. Publish -> Recommended (active, supported) 3. Realize -> Active (supported, scheduled for retirement) 4. Maintain -> Retired (still active, but unsupported and scheduled for deactivation) 5. Retire -> Deactivated — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#7 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABSV3OXLWVNKPZPE6VXHTHTRQQS2BANCNFSM4IDVDKXQ> .

[dret]

On 2020-05-14 19:44, dberlind wrote: It's good to see that the CAM model agrees that 5 stages pretty much covers all possibilities. No reason to over complicate things.

just for clarification: all we're saying in the CAM book is that an org should have a lifecycle model. the one we're using is just an example, but we're not saying that it's the one true lifecycle model. in my mind, trying to define a canonical lifecycle model is probably not a great idea. maybe support one "standard one" that you like, but definitely be open to the reality that different orgs will have different ones that do not map to the "standard one".