Enhanced Operation Deprecation and versioning

Currently, OpenAPI allows us to identify the version of the API being described and deprecate operations using a Boolean value.

I would like to propose some additional metadata that makes it easier to track changes to APIs. In addition to the existing deprecated flag, there is now a deprecatedVersion and replacementOperationId property.

Consider the following API and two of its operations:

{
 "openapi" : "3.0.0",
 "info" :  {
      "title" : "My API",
      "version" : "1.0.313"
  }
{
    "/foo" : {
        "get" : {
             "operationId" : "getFoo",
             "description" : "Return a foo",
             "deprecated" : true,
             "deprecatedVersion" : "1.0.312",
             "replacementOperationId" : "getFoo2"
             "responses" : {
                 "200" : {
                        "description" : "A foo representation"
                 }
             } 

        },
   "/foo2" : {
        "get" : {
             "operationId" : "getFoo2",
             "description" : "Return a foo",
             "responses" : {
                 "200" : {
                     "description" : "A completely different breaking foo representation"   
                 }
             } 
        }
    }
}
}

The deprecatedVersion property indicates the API version in which this operation was deprecated. The replacementOperationId provides a pointer to a new operation that replaces the functionality of the deprecated operation.

These new properties enable a variety of useful capabilities:

• Display documentation that is relevant to a particular API version. Operations that were deprecated prior to that version can be hidden by default to prevent accidently usage of operations that have been replaced.
• Help developers migrate to new operations by allowing documentation of deprecated operations to point to replacement operations.
• Generate client code that only supports operations available in a particular API version.
• Makes it possible to manage APIs to that are changing incrementally instead of doing big bang updates that completely replace a prior API.
• Help developers identify what has changed in a new API release.

[timburks]

We would like to also be able to mark an entire API as deprecated. Repeating some internal discussion:

The simplest change to support this would be to add the “deprecated” property at the top level (the “root document object”). If the property is true, the API is deprecated; if not, it’s still active.

For API deprecation, some additional information might be useful:

• The date of the original deprecation.
• The date of final shutdown.
• Deprecation strategy:
  • Are new users permitted or forbidden?
  • Is there any SLO for this API?
  • Is there any system degradation due to the deprecation (eg. higher latency, intermittent errors, lower quotas, warning messages in response headers, etc)? This could either be purely informative or this setting could directly affect how the backend behaves.
  • Links to any replacement APIs.

[sdatspun2]

i would refine @dret’s comment above. There are two relevant HTTP headers for deprecation: Deprecation (https://tools.ietf.org/html/draft-dalal-deprecation-header-00) and Sunset. To inform about the deprecation, the Deprecation HTTP header should be used. To inform about sunset of the deprecated resource, the Sunset header should be used in addition to the Deprecation header. This is described in section #5 https://tools.ietf.org/html/draft-dalal-deprecation-header-00#section-5.

Draft #11 https://tools.ietf.org/html/draft-wilde-sunset-header-11 of the Sunset header clarifies this aspect as well in section 1.4 https://tools.ietf.org/html/draft-wilde-sunset-header-11#section-1.4.