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

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

[kinlane]

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.

[dberlind]

All fair points @Stu. When I originated this thread (see https://github.com/OAI/OpenAPI-Specification/issues/1397 from almost 4 years ago), the main value proposition behind my idea was discovery. The implications of “landing” on one version and then being able to find the others, if they exist (essentially traversing a version graph), has enormous implications and benefits for consuming developers (never mind the automation of discovery and the possible outcomes of that). But the original objective got subsumed into a larger conversation. IMHO, the efficacy of the original proposal is still something aspire to (and works regardless of whether the changes are breaking or not). Let’s get that alone into play (and practice) and then iterate from there.

On Mon, Aug 2, 2021 at 12:24 PM Stu Waldron @.***> wrote:

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.

— 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-891159623, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABSV3OXU3QEYLIKOTFRDFC3T23BCXANCNFSM4IDVDKXQ .