Partial deprecation

To discourage the use of an endpoint or a specific element within an endpoint that will not be supported in future API releases, the API team must mark it as deprecated. Use the deprecated property in the OpenAPI Specification (OAS) to indicate this.

With partial deprecation, the item marked as deprecated must remain supported for the life of that major API version in order to not break existing consumers who may 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.
• API teams must increment the minor version and explain the deprecation made in the release note for that release, when deprecating an endpoint or element.

Deprecated elements still need to be supported and often become expensive to maintain. Therefore, API teams will eventually 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, header, or property on a resource would be considered a breaking change for a consumer when it is removed. Therefore, announce the deprecation, guide the consumer to the new alternative, if available, continue to support it, and wait until the next major version of the API to remove it.

To highlight that it is deprecated, add the word "Deprecated" as the first word in the description field for that element and also to the summary field if the element is an endpoint. Inform the consumer to what they should now use.

Endpoint deprecated

paths:
  /legacy-appeals:
    get:
      summary:  Deprecated endpoint.  Use `GET /appeals` endpoint instead.
      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

Note: Both the summary and description fields mention the endpoint is deprecated. Move any necessary information that was in summary to the description. Guide the consumer to the alternative endpoint that is replacing the one being deprecated, if there is one.

Query parameter deprecated

paths:
  /appeals:
    get:
      description: Retrieve appeals status
      parameters:
        - name: fromDate
          in: query
          description: Deprecated `fromDate` query parameter, 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: Deprecated the `ORG-Authorization-Token` header. The value in this header is now ignored and the information is acquired using the value within the JSON Web Token (JWT).
          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. 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 provides
            greater granularity of the option chosen.
          deprecated: true