Partial deprecation

Between major version releases, an API team may want to deprecate an endpoint or an element of an API rather than the entire API version. The OpenAPI Specification uses a deprecated field to mark complete endpoints or their specific elements as deprecated.

In this form of deprecation, the item marked as deprecated still needs to be supported so functionality does not break for existing consumers who may still be using it.

Requirement

• API teams must document deprecated endpoints and elements in the OAS.
• Deprecated API endpoints and elements must remain supported for the life of the major version.
• When deprecating an endpoint or element, API teams must increment the minor version and publish the deprecation made in the release note for that release.

Since deprecated elements still need to be supported, they can become expensive to maintain. Therefore, eventually the API team will want to create a new major version to remove the deprecated parts, and then deprecate the previous version.

Examples of Partial Deprecation

A deprecated endpoint, query parameter, or property on a resource would typically be considered a breaking change for a consumer when it is removed. Therefore, it is appropriate to announce the deprecation, guide the consumer to the new option if available, and wait until the next major version of the API to remove it.

Endpoint deprecated

paths:
  /legacy_appeals:
    get:
      description: Deprecated endpoint to retrieve legacy appeals.
        Use the new `GET /appeals` endpoint instead which will return 
        this same information, plus handle various states of appeals.
      deprecated: true

Query parameter deprecated

paths:
  /appeals:
    get:
      description: Retrieve appeals status
      parameters:
        - name: fromDate
          in: query
          description: Deprecated `fromDate` query parameter, please
           use the new `months` query parameter instead.
          deprecated: true

Header deprecated

paths:
  /appeals:
    get:
      description: Retrieve appeals status
      parameters:
        - name: ORG-Authorization-Token
          in: header
          description: The `ORG-Authorization-Token` header is deprecated 
            and is no longer necessary to send. This value is now ignored
            and the information is acquired using the JSON Web Token (JWT) 
            value.
          deprecated: true

Property deprecated within a resource

paths:
  /appeals:
    get:
      description: Retrieve appeals status
      responses:
        200:
          description: Successful appeal
          content:
            application/json:
              schema:
                $ref: “#/components/schemas/Appeal”
components:
  schemas:
    Appeal:
      description: Appeal status schema
      properties:
        appealType:
          type: string
          description: Deprecated `appealType`, which is the decision review
            option chosen by the appellant. Please use the new property
            `chosenAppealOption`. The deprecated `appealType` will remain
            populated and should match the value in the new property
            `chosenAppealOption` as best it can. The new property will
            contain greater granularity of the option chosen.
          deprecated: true