search

OAI / OpenAPI-Specification

The OpenAPI Specification Repository
https://openapis.org
Apache License 2.0
28.93k stars 9.07k forks source link

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

Open ioggstream opened 5 years ago

ioggstream commented 5 years ago

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

Related to

1397

ioggstream commented 5 years ago

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

dberlind commented 5 years ago

@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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

@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 commented 4 years ago

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 commented 4 years ago

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 notifications@github.com 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 commented 4 years ago

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 commented 4 years ago

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

lorenzino commented 4 years ago

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 commented 4 years ago

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 commented 3 years ago

@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"
dvh commented 3 years ago

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 commented 3 years ago

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

swaldron58 commented 3 years ago

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 commented 3 years ago

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 .

swaldron58 commented 3 years ago

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 commented 3 years ago

The number thing was probably sheer coincidence. Maybe go play those numbers in the local lottery? I think my main point is to create a system whose predictability is clear and not compromised by requirements in flexibility. To create a chain of versions, one OAS spec per version will work regardless of the major/minor versioning approach. Should you decide to edit an existing OAS file for a minor version change (versus generating a new one), it should allow for that (though I think it's better to have separate OAS files for all versions, major or minor). 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. All this said, I have no influence over the outcome. When I originally proposed the idea four years ago, I was looking ahead to now when the efficacy would be clear given the proliferation of APIs and the need to manage them. Particularly for architectural styles like REST where the description lives out of band (unlike GraphQL and gRPC where it's "in-band"). Back then, I was told the idea was out-of-scope for OAS (I think that's reflected in the thread). So, I tucked my tail and went home. Then later, there seemed to be a change of heart (also reflected in the thread) and suddenly the conversation was revived. So, I have been monitoring it because I still think the base idea is still of critical importance and would love to see it come to fruition on of these days.

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

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 https://github.com/OAI/OpenAPI-Specification/issues/1973 and #1397 https://github.com/OAI/OpenAPI-Specification/issues/1397? I at first thought someone transposed the numbers in a post.

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

swaldron58 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

@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 commented 3 years ago

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 commented 3 years ago

@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 commented 3 years ago

Hey all, I realize there is tremendous efficacy to the many proposed "extensions" to the original proposal https://github.com/OAI/OpenAPI-Specification/issues/1397#issue-270732827. However, as you can see from the many suggestions, everyone has ideas on what works and doesn't work for these different nuances. What I originally proposed is dirt simple (the formatting on the following may get screwed up due to my use of email reply).

info: version: 2.4.1 (this version) previousVersion: nextVersion: productionStatus: Pre-Release

For production status, you can leave it completely open to the organization to decide what

standard language works best for them. For those seeking opinionated guidance, here

is one suggestion for productionStatus possibilities.

  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

I recommend staying away from the word "deprecated" because of how ambiguous it is (equates to

different things for different orgs)

Anyway, this is dirt simple and the efficacy of this alone would be amazing. i realize from the original discussion that I myself participated in feature creep. I regret this in hindsight because of how that conversation appears to have stalled progress for almost four years. How about we just MVP this with the very simple initial proposal and then iterate from there rather than trying to come up with something that covers every possibility, links off to other specs, etc. Perfect is the enemy of good enough.

On Thu, Aug 5, 2021 at 11:16 AM Dimitri van Hees @.***> wrote:

@swaldron58 https://github.com/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 ;-)

— 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-893542273, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABSV3OT5HDUOWB2Q36FYFCDT3KTLPANCNFSM4IDVDKXQ . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&utm_campaign=notification-email .

dvh commented 3 years ago

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 commented 3 years ago

thanks Dimitri. See https://github.com/OAI/OpenAPI-Specification/issues/1397#issuecomment-355610529

On Thu, Aug 5, 2021 at 11:47 AM Dimitri van Hees @.***> wrote:

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

— 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-893565513, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABSV3OUOAQYABVWS4IL4FOTT3KW77ANCNFSM4IDVDKXQ . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&utm_campaign=notification-email .

kinlane commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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.