[ADP-127] Deprecation

Guidance

• When a resource or API has a new version, you SHOULD use the Deprecation header to inform the deprecation date and use the Link header to inform the client of the alternative, using the registered relation type alternate. The value type should be a structured filter date as defined in https://datatracker.ietf.org/doc/draft-ietf-httpbis-sfbis/

  GET /v1/resources HTTP/1.1
  
  HTTP/1.1 200 OK
  Deprecation: @123456789
  Link: </v2/resources>; rel="alternate",
        <https://dev.doc/deprecation-policy>; rel="deprecation"

• You MAY provide a link with the relation type deprecation to inform the client where to find deprecation information.

  Link: <https://developer.example.com/deprecation>;
           rel="deprecation"; type="text/html"

Example

Example with OpenAPI

openapi: 3.1.0
info:
  title: Example API
  version: 1.0.0
paths:
  /v1/resources:
    get:
      summary: Get resources (deprecated)
      deprecated: true
      responses:
        '200':
          description: Successful response
          headers:
            Deprecation:
              description: Indicates that the API version is deprecated
              schema:
                type: string
                example: '@123456789'
            Link:
              description: Provides links to the new version and deprecation policy
              schema:
                type: string
                example: '</v2/resources>; rel="alternate", <https://dev.doc/deprecation-policy>; rel="deprecation"'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        value:
                          type: string
  /v2/resources:
    get:
      summary: Get resources (new version)
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        value:
                          type: string

Relative ADPs

• ADP-42: API lifecycles

Reference

• https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-deprecation-header

  Notice: it's still a draft and may change later.

• https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel