How to deprecate an entire API in OpenAPI?

Question

I would like to find a way to mark an API as deprecated.

Here is a possible case: instead of REST API, GraphQL API is developed, but in order to smoothly decommission the old REST API, I would like to first mark it as deprecated. I would like to do this with the least amount of edits (without marking each operation as deprecated).

Answer 1

deprecated is only officially supported at the operation, parameter or on schema attributes

You can always use a custom x-deprecated at the root of the OpenAPI file. Not sure many tools will support it. Otherwise, the deprecated should be defined at each operation.

Here's a sample of that and a recommended deprecation strategy for your services.

When you mark the api deprecated, inform your consumers of this with headers. Continue returning 200 and give them the deprecation date, the sunset date of the service and a link to a replacement, if one exists.

After the deprecation date has passed, return a 410 on the service until the sunset date is reached and provide a link to the replacement.

openapi: 3.0.4
info:
  title: a sample api deprecation
  version: 1.0.0
x-deprecated: true
paths:
  '/thing':
    get:
      summary: my old api
      deprecated: true
      responses:
        '200':
          description: OK
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
            Link:
              $ref: '#/components/headers/Link'
          content:
            'application/json':
              schema: {}
        '410':
          description: Gone
          headers:
            Sunset:
              $ref: '#/components/headers/Sunset'
            Link:
              $ref: '#/components/headers/Link'
          content:
            'application/json':
              schema: {}
components:
  headers:
    Deprecation:
      description: Contains the version and/or datetime of a deprecated resource
        related to the request URI.
      required: false
      schema:
        type: string
      examples:
        deprecation:
          value: '"deprecation": "version =v1; date = "2024-04-30T00:00:00Z"'
    Sunset:
      description: 'Contains the retirement datetime of a resource related to the
        request URI. Note: For historical reasons the datetime format differs from
        the Deprecation datetime format.[Dalal et al. (2023)]'
      required: false
      schema:
        type: string
      examples:
        sunset:
          value: '"sunset": "Fri 8 Mar 2024 23:59:00 GMT"'
    Link:
      description: Expresses a typed relationship with another resource
      required: false
      schema:
        type: string
        format: uri