Skip to main content

API Deprecation

Deprecating an API signals that it is scheduled to be phased out. With Traefik Hub, you can use OpenAPI’s built-in fields to indicate that an entire API version or a specific endpoint is deprecated.

Using the Deprecated Field​

OpenAPI allows you to mark an endpoint as deprecated by adding deprecated: true to its definition. For example:

paths:
  /old-endpoint:
    get:
      summary: Old endpoint
      description: This endpoint is deprecated and will be removed in a future release.
      deprecated: true
      responses:
        '200':
          description: OK

Including Deprecation Details in description​

To explain why an endpoint is deprecated or to provide a retirement date, add details in the description field of its OpenAPI spec. For example:

paths:
  /old-endpoint:
    get:
      summary: Old endpoint
      description: This endpoint will be removed on December 31, 2025. Use `/new-endpoint` instead.
      deprecated: true

Deprecating an Entire API Version​

If you want to deprecate a whole API or API Version, include a note in the info section of your OpenAPI spec:

openapi: 3.0.0
info:
  title: Example API
  version: '1.0'
  description: >-
    Version 1.0 is deprecated. It will no longer be supported after December 31, 2025.
    Please migrate to version 2.0.
paths:
  ...

Once you update the specification following any of the above methods, Traefik Hub will serve it as defined on the API portal. To learn more about these fields, see the OpenAPI Specification.

Sample OpenAPI Specification and API Portal View​

Below is a sample OpenAPI spec that includes fields for deprecation, along with a demonstration of how it appears in the Traefik Hub API portal:

openapi: 3.0.2
info:
  title: Swagger Petstore - OpenAPI 3.0
  description: |-
    This is a sample Pet Store Server based on the OpenAPI 3.0 specification. Version 1.0 is deprecated. It will no longer be supported after December 31, 2025.
    Please migrate to version 2.0.

    Some useful links:
    - [The Pet Store repository](https://github.com/swagger-api/swagger-petstore)
    - [The source API definition for the Pet Store](https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml)
  termsOfService: 'http://swagger.io/terms/'
  contact:
    email: [email protected]
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
  version: 1.0.19
externalDocs:
  description: Find out more about Swagger
  url: 'http://swagger.io'
servers:
  - url: /api/v3
tags:
  - name: pet
    description: Everything about your Pets
    externalDocs:
      description: Find out more
      url: 'http://swagger.io'
  - name: store
    description: Access to Petstore orders
    externalDocs:
      description: Find out more about our store
      url: 'http://swagger.io'
  - name: user
    description: Operations about user
paths:
  /pet:
    put:
      tags:
        - pet
      summary: Update an existing pet
      description: Update an existing pet by Id
      deprecated: true
      operationId: updatePet
      requestBody:
        description: Update an existent pet in the store
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
          application/xml:
            schema:
              $ref: '#/components/schemas/Pet'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Pet'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Pet'
              examples: {}
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
              examples:
                Example 1:
                  value:
                    id: 10
                    name: doggie
                    category:
                      id: 1
                      name: Dogs
                    photoUrls:
                      - string
                    tags:
                      - id: 0
                        name: string
                    status: available
        '400':
          description: Invalid ID supplied
        '404':
          description: Pet not found
        '405':
          description: Validation exception
      security:
        - petstore_auth:
            - 'write:pets'
            - 'read:pets'
# ...