Add deprecation metadata for our REST API to its OpenAPI data

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

• Close this issue

About

Our REST API currently lacks the ability for us to describe deprecations through metadata, like our GraphQL API does.

The OpenAPI spec allows deprecated booleans.

The metadata is useful as a means for clients to be informed of deprecations.

We can also use this data internally to:

• Track use of deprecation items (for example, logging the use like GraphQL).
• Describe the deprecation in generated docs.
• Allow the ability to show/alert people their use of deprecated items #341095 (closed).

Proposal

We should:

• Use the OpenAPI deprecated property in our REST API.
• Document/form a process for developers to use this property.

Ideally, we would also add the same deprecation metadata as GraphQL, which includes:

• Deprecation reason (a human-readable description of the deprecation)
• Milestone that the item was deprecated.