Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add info.lifecycle with maturity/lifecycle informations. #1973

Open
ioggstream opened this issue Jul 15, 2019 · 32 comments
Open

Add info.lifecycle with maturity/lifecycle informations. #1973

ioggstream opened this issue Jul 15, 2019 · 32 comments
Labels
metadata tags, info, license, contact, markdown usage, etc. versioning describing versions of APIs/endpoints/operations

Comments

@ioggstream
Copy link
Contributor

ioggstream commented Jul 15, 2019 •
edited
Loading

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
Copy link
Contributor Author

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

@dberlind
Copy link

@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
Copy link

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
Copy link
Contributor

dret commented Jul 16, 2019 via email

@dberlind
Copy link

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
Copy link
Member

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
Copy link
Contributor Author

ioggstream commented Jul 31, 2019 •
edited
Loading

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

This was referenced Jan 16, 2020
Open
Open
@ioggstream ioggstream changed the title Add info.lifecycle with lifecycle informations. Add info.maturity with maturity/lifecycle informations. May 8, 2020
@ioggstream ioggstream changed the title Add info.maturity with maturity/lifecycle informations. Add info.lifecycle with maturity/lifecycle informations. May 8, 2020
@ioggstream
Copy link
Contributor Author

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
Copy link

dberlind commented May 14, 2020 via email

@dret
Copy link
Contributor

dret commented May 15, 2020 via email

@MikeRalphson MikeRalphson mentioned this issue Jul 30, 2020
Open
@ioggstream
Copy link
Contributor Author

@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
Copy link

lorenzino commented Sep 1, 2020 •
edited
Loading

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] SEMICeu/DCAT-AP#86
[7] w3c/dxwg#1238

@rrance-va
Copy link

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.

@cebe cebe mentioned this issue Oct 1, 2020
Closed
@ioggstream
Copy link
Contributor Author

ioggstream commented Nov 25, 2020 •
edited
Loading

@lorenzino if we follow the different threads proposed in #1973 (comment) 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"

@dvh
Copy link

dvh commented Apr 30, 2021

Since I found out that info.version is actually the version of the spec and there is no dedicated way to specify the version of the API, I really think this should be in scope for OAS. Having the corresponding API version in OAS is part of a bigger 'lifecycle' feature. However, when put in the spec it could be very hard to maintain. Therefore I think the version information itself should be living outside the spec, and there should be a link to it in the spec.

If this link is available, tooling might follow it in order to retrieve corresponding API version information. Now this asks for a standardized machine-readable way to describe the lifecycle status. Imagine something like lifecycleStatus: "https://localhost/lifecycleStatus?version=2.0.0" or lifecycleStatus: "https://lifecycle.myapi.com/938434".

If both endpoints return a machine readable response of a (to be developed?) "lifecycle information specification object" you can start discovering versions from there without having to maintain all the specs.

@ioggstream
Copy link
Contributor Author

@dvh The APIs4IPS workgroup made a proposal related to edelivery. @lorenzino, could you provide some references please?

@earth2marsh earth2marsh mentioned this issue May 13, 2021
Closed
17 tasks
@swaldron58
Copy link

I did a quick read catching up so apologize if I missed it. I didn't see anything on what versions mean, specifically minor versus major. With Open Travel 2.0 we take versioning very seriously and it is built into the tooling we created. We model at the domain level and versions, hand in hand with namespaces, it very specific. The "API" is defined in the model and hence the version of the API is derived from the model. We also have a policy that minor version changes may only be non-braking changes such as extensions of the model. A completion criteria of an implemented API is that no extension of the model (a new element name) does not cause an error. The job of the developer is to ignore what they have not seen before rather than barf all over it. If the structure (relationships) of the model changed in any way, all bets are off and it is a major version change. It is understood everyone will have to at least retest if not make code changes.
My main points being and also expressed in posts by others is the version of the API is not in isolation. Schema/model, namespaces, source code and more is involved. I think there also needs to be a clear delineation and policy statements on what major versus minor means the behaviors expected. Very welcomed any clarity in how to express an API version but there is a wider context to also communicate.

@dberlind
Copy link

dberlind commented Aug 2, 2021 via email

@swaldron58
Copy link

Makes sense. Still being a bit new to this, should I go ahead and open new issues on some of the points I made so they don't get lost? For example settling on a OAI definition (if one does not already exist) on what major and minor versions mean can happen concurrently. BTW, how did two related issues use the same numbers, #1973 and #1397? I at first thought someone transposed the numbers in a post.

@dberlind
Copy link

dberlind commented Aug 2, 2021 via email

@swaldron58
Copy link

All makes sense. I will refer to this exchange in #sig-lifecycle. The statement "This construct also
does not impose requirements when it comes to one organization's approach to "what is minor?, what is major?" versus another. So, the flexibility is there. ". While the OAS spec may not get specific on a particular version policy, a SIG like SIG-travel will. Versioning chaos is a significant contributor to API chaos. It's costing the travel industry millions due to the labor to support the thousands of bespoke APIs to deal with when trying to pull together trip level solutions.

@kinlane
Copy link

kinlane commented Aug 4, 2021 •
edited
Loading

Our team is firing up a weekly conversation around defining extensions for the API lifecycle, beginning with OpenAPI, but then also AsyncAPI and JSON Schema. We threw together a proof of concept extension after some discussion today:

# An extension for OpenAPI
x-lifecycle:

  # Navigating Change
  version:
      current: 'http://example.com/next'
      next: 'http://example.com/next'
      previous: 'http://example.com/next'

  # Development
  # Staging
  # Production
  environments: 

      # Environment for development
      - name: Development
        url: 'https://www.postman.com/environment'  
        variables:
            base_url: 'http://example.com/development'       
            api_key: 'xe3847d3J78393jkdm1123'  

      # Environment for production
      - name: Production
        url: 'https://www.postman.com/environment'  
        variables:
            base_url: 'http://example.com/production'       
            api_key: 'xe3847d3J78393jkdm1123'                

  # Design
  # Pre-Release    
  # Active
  # Recommended
  # Retired
  # Deprecated
  maturity: 'Active'

  # Public
  # Internal
  # Group
  # Partner
  visibility: 'Public'

  # Essential Building Blocks of the API Lifecycle
  buildingBlocks:

      # All Documentation
      documentation:

          # Reference Documentation
          - type: reference
            title: Reference Documentation
            url: 'https://example.com/documentation'
            collection: 'https://www.postman.com/collection'

          # Workflow Documentation
          - type: workflow
            title: Workflow Documentation
            url: 'https://example.com/documentation'
            collection: 'https://www.postman.com/collection'

      # All Tests
      tests:

          - type: contract
            title: Contract Testing
            url: 'https://example.com/contract-testing'
            collection: 'https://www.postman.com/collection'

          - type: performance
            title: Performance Testing
            url: 'https://example.com/performance-testing'
            collection: 'https://www.postman.com/collection'

          - type: security
            title: OWASP Top 10
            url: 'https://example.com/owasp-security-testing'
            collection: 'https://www.postman.com/collection'

      # All Mocks
      mocks:

          - type: sandbox
            title: Mock Server
            url: 'https://example.com/mock'
            collection: 'https://www.postman.com/collection'

      # All Monitors
      monitors:

          - type: uptime
            title: Uptime Monitor
            url: 'https://example.com/monitor'
            collection: 'https://www.postman.com/collection'
            environment: 'https://www.postman.com/environment'

          - type: performance
            title: Regional Performance Monitor
            url: 'https://example.com/monitor'
            collection: 'https://www.postman.com/collection'
            environment: 'https://www.postman.com/environment'

      # All Reports
      reports:

          - type: overview
            title: Dashboard
            url: 'https://example.com/monitor' 
            collection: 'https://www.postman.com/collection'           

  # Milestones for the API
  milestones:

      # Design
      - type: design
        description: 'Design agreed upon by stakeholders.'
        date: '2021-05-01'

      # Review
      - type: review
        description: 'Wentn through architectural review.'
        date: '2021-06-01'          

      # Staging
      - type: staging
        description: 'Left staging phase of development.'
        date: '2021-07-01'

      # Active
      - type: active
        description: 'Put into production as active API.'
        date: '2021-07-15'

Would love any thoughts. Here is my narrative around this iteration, and you are welcome to leave inline comments on the extension in it's workspace.

@dvh
Copy link

dvh commented Aug 5, 2021 •
edited
Loading

@kinlane nice! From your post:

Historically I do not believe that any of this should live within OAS, and I feel it should live within the APIs.json / APIs.yaml index for an API [...]

I completely agree on this. Describing API lifecycle information could be a specification of it's own, and by adding it to OAS it might make OAS overcomplicated for both it's maintainers and users. Also, by separating lifecycle information from OAS, it might be easier to maintain/generate as an API provider. In fact, if an API itself becomes deprecated and it's added to x-lifecycle part of the OAS file, the info.version should be updated as well, as this is actually the version of the OAS file itself... ;-)

I'd love to see a new OAS property which can be used to point to an external location containing the lifecycle information following a specification like this. OAS tools can then resolve it to show more information about the actual API version, where I think the property maturity might be the lowest hanging fruit... That is apart from the actual current API version, which cannot be described at all with OAS at the moment.

@swaldron58
Copy link

I agree with the statement "Describing API lifecycle information could be a specification of it's own" but have a follow up question on the difference between a specification and an architecture. Both terms are often loosely defined. With #sig-travel I intend to publish via the Open Travel Alliance standards body a reference architecture documenting how (in travel APIs) versioning across the API lifecycle should be done. Referencing the OAS where applicable. Again I agree with API lifecycle being a sperate specification but, @dvh or @kinlane, can you expand a little more on what would be in said specification?

@dvh
Copy link

dvh commented Aug 5, 2021 •
edited
Loading

@swaldron58 I'm happy as long as we all use the same machine-readable way to publish this information ;-)

However, by also doing this according to the OAS guidelines (naming conventions, yaml/json, etc.), the chance of OAS tools adopting it is even bigger. E.g. I wouldn't be eager to support "the lifecycle extension" in my tool if I suddenly have to parse XML as well...

@dberlind
Copy link

dberlind commented Aug 5, 2021 via email

@dvh
Copy link

dvh commented Aug 5, 2021 •
edited
Loading

I could live with that as well, but then we still need to have something like an info.apiVersion property in OAS. Because if I understand it right, info.version refers to the OAS document itself and is being misused as the version of the API by many (including me 😄).

@dberlind
Copy link

dberlind commented Aug 5, 2021 via email

@kinlane
Copy link

kinlane commented Aug 6, 2021

I updated with some simple, basic, and intermediate examples based upon interviews with 13 folks about what the API lifecycle is - https://apievangelist.com/2021/08/05/the-dimensions-of-the-api-lifecycle/

I also agree about extension, except for the fact that all the OAI has to do is begin sanctioning and promoting first class extensions and they'd be seen along side the core -- adding to the already significant proliferation and reuse of existing extensions that are in use today. If you only pay attention to spec you don't see extensions. Doesn't take much to bring them into view -- they are everywhere.

@kinlane
Copy link

kinlane commented Aug 6, 2021

My proposal has the basic example:

# An extension for OpenAPI
x-lifecycle:

  # Navigating Change
  version:
      current: 'http://example.com/next'
      next: 'http://example.com/next'
      previous: 'http://example.com/next'

  # Development
  # Staging
  # Production
  environments: 

      # Environment for production
      - name: Production
        url: 'https://www.postman.com/environment'  
        variables:
            base_url: 'http://example.com/production'       
            api_key: 'xe3847d3J78393jkdm1123'                

  # Design
  # Pre-Release    
  # Active
  # Recommended
  # Retired
  # Deprecated
  maturity: 'Active'

  # Public
  # Internal
  # Group
  # Partner
  visibility: 'Public'

While this is good, in my interviews with 13 API practitioners, only 1 mentioned these properties. The API lifecycle is "seen" through docs, tests, etc., which is why I included those options as well.

@kinlane
Copy link

kinlane commented Aug 6, 2021

I would say that this more reflects how people see the API lifecycle:

# An extension for OpenAPI
x-lifecycle:

  # Navigating Change
  version:
      current: 'http://example.com/next'
      next: 'http://example.com/next'
      previous: 'http://example.com/next'

  # Development
  # Staging
  # Production
  environments: 

      # Environment for production
      - name: Production
        url: 'https://www.postman.com/environment'  
        variables:
            base_url: 'http://example.com/production'       
            api_key: 'xe3847d3J78393jkdm1123'                

  # Design
  # Pre-Release    
  # Active
  # Recommended
  # Retired
  # Deprecated
  maturity: 'Active'

  # Public
  # Internal
  # Group
  # Partner
  visibility: 'Public'

  # Elements of the API Lifecycle
  elements:       

      # Documentation
      documentation:

          label: Docs
          guidance: http://example.com/guidance
          elements:

              # Reference Documentation
              - type: reference
                title: Reference Documentation
                url: 'https://example.com/documentation'
                collection: 'https://www.postman.com/collection'                                             

      # All Tests
      tests:

          label: Testing
          guidance: http://example.com/guidance
          elements:              

              - type: contract
                title: Contract Testing
                url: 'https://example.com/contract-testing'
                collection: 'https://www.postman.com/collection'

      # All Monitors
      monitors:

          label: Monitors
          elements:              

              - type: contract
                title: Contract Testing Monitor
                url: 'https://example.com/monitor'
                collection: 'https://www.postman.com/collection'
                environment: 'https://www.postman.com/environment'

@dvh
Copy link

dvh commented Aug 6, 2021

Personally I've got two thoughts about this, and perhaps these should be two different issues/discussions:

  1. When it comes to API lifecycle, this could be an extension/spec on it's own. Because as you can see in the examples from @kinlane, there are multiple aspects regarding the API lifecycle, and a lot of them could be optional.
  2. When it comes to a (imho) missing feature in OAS, is a way to describe the actual version and the maturity of an API; both properties are so important that there are even ways to express them via HTTP response headers. While 'developer experience' and 'devrel' are trending topics nowadays, a widely adopted spec like OAS should at least support these properties in the core. But once again, that's my opinion.

And then there is the 'discoverability' of APIs. How much I wished this was part of OAS as I need this for most of my usecases, I honestly think this belongs somewhere in the middle of the points mentioned above.

@earth2marsh earth2marsh mentioned this issue Nov 18, 2021
Merged
@handrews handrews added the metadata tags, info, license, contact, markdown usage, etc. label Jan 29, 2024
@OAI OAI deleted a comment from jeffskilling Apr 7, 2024
@LasneF LasneF added the versioning describing versions of APIs/endpoints/operations label Aug 6, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
metadata tags, info, license, contact, markdown usage, etc. versioning describing versions of APIs/endpoints/operations
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests