Define standards to deprecate in Rest Api Spec

[mayya-sharipova]

It seems that we don't have a standard to deprecate APIs or part of APIs (fields, methods etc) in our Rest API specification files:
rest-api-spec/src/main/resources/rest-api-spec/api/*.json

In this issue we can propose possible ways to define deprecations, and come up with a single standard way.

relates to #34771

[mayya-sharipova]

My suggestion is to add a "deprecated" object field to the specification:
For example:

"deprecated" : {
  "version": "5.0",
  "description" : "Use regular count endpoint instead."
}

And depending what is deprecated (main API, or a field) put it on the corresponding level.

Example - the whole API is deprecated:

{
  "count_percolate": {
    "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/5.x/search-percolate.html",
    "methods": ["GET", "POST"],
    "url": {},
    "body" : {},
    "deprecated" : {
      "version": "5.0",
      "description" : "Use regular count endpoint instead."
   }
}

[elasticmachine]

Pinging @elastic/es-core-infra

[Mpdreamz]

Love this proposal, would love to help out getting this into the rest spec.

One remaining question I have is around deprecated urls paths.

In #38102 I proposed:

"deprecated_paths": ["/{index}/{type}/{id}"]

But perhaps the following falls more in line with your proposal @mayya-sharipova

"deprecated_paths": [ { "url": "/{index}/{type}/{id}", "version": "5.0", "description": "" } ]

cc @elastic/es-clients

[mayya-sharipova]

closing the issue, as it will be addressed by #39063