Openapi-specification: 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

1397

[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 [e-mail]
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
https://github.com/OAI/OpenAPI-Specification/issues/1973#issuecomment-625880908,
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".

[ioggstream]

@lorenzino @mgboydcom here we have various threads to follow:

• where to store those lifecycle information;
• define a registry for product phases: as @dret says you should be free to set your phases;
• identify a syntax (eg. etiketo?).

[lorenzino]

Agree with @dret: there should be the possibility to adopt either a 'default' (documented in a registry) one (i.e. one proposed by OAS if no lifecycle is adopted by the organisation, e.g. the one of CAM) or another documented one adopted by organisation.

For example the DCAT-AP [1] defines the property 'status' for that '_refers to the maturity of the Distribution. It MUST take one of the values Completed, Deprecated, Under Development, Withdrawn_' and which URI is 'adms:status'. Then, the European Environmental Agency defines this list differently [2].

DCAT-AP proposes 4 statuses for an 'asset' [4] that might match the ones of CAM and the Berlind ones as follows:

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

A more complete list of values for a 'concept' have been defined by the EU publication office at [5]
A parallel discussion for DCAT-AP/datasets/distribution statuses is at [6] and [7]

[1] https://joinup.ec.europa.eu/collection/semantic-interoperability-community-semic/solution/dcat-application-profile-data-portals-europe/release/201-0
[2] https://dd.eionet.europa.eu/dataelements/78977
[3] https://inspire.ec.europa.eu/registry/status
[4] https://www.w3.org/2012/06/tr2adms/
[5] https://op.europa.eu/en/web/eu-vocabularies/at-concept-scheme/-/resource/authority/concept-status
[6] https://github.com/SEMICeu/DCAT-AP/issues/86
[7] https://github.com/w3c/dxwg/issues/1238

[rrance-va]

This is an interesting discussion. I've started to use extensions for the same purpose however instead of indicating the status at the info level I am adding it to each operation, parameter and property in the body. That way I can continually evolve my API without needing to put version numbers in the path.

In addition to the statuses proposed above I would like to see a Proposed status that comes before Pre-Release/beta. I'm using it as a way to communicate to our users the features we are considering adding and looking for feedback on.

[ioggstream]

@lorenzino if we follow the different threads proposed in https://github.com/OAI/OpenAPI-Specification/issues/1973#issuecomment-682418401 I would say that on an experimental project

Picking the label

The property for the acme project could be info.x-acme-lifecycle.

Defining the Lifecycle object

The open point is the "schema" for the underlying object: "maturity" is only one lifecycle information (eg. Completed, Deprecated, Under Development, Withdrawn).

We need to provide more information and dates.

Probably the following example has too-much linked data stuffed in, but it can be fixed in some way :)

info.lifecycle:
  labels:
    "https://twitter.com/thecambook/maturity": "publish"
    "http://www.w3.org/ns/adms#adms:status": "Completed"
    "http://purl.org/adms/status/Withdrawn": "2021-10-20"