Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[7.2] Documents the new deprecations options on the rest-api-spec (#41444) #43089

Merged
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 72 additions & 1 deletion rest-api-spec/README.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,6 @@ Example for the ["Create Index"](http://www.elastic.co/guide/en/elasticsearch/re
"documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/indices-create-index.html",
"methods": ["PUT", "POST"],
"url": {
"path": "/{index}",
"paths": ["/{index}"],
"parts": {
"index": {
Expand Down Expand Up @@ -46,6 +45,78 @@ The specification contains:
The `methods` and `url.paths` elements list all possible HTTP methods and URLs for the endpoint;
it is the responsibility of the developer to use this information for a sensible API on the target platform.

## Backwards compatibility

The specification follows the same backward compatibility guarantees as Elasticsearch.

- Within a Major, additions only.
- If an item has been documented wrong it should be deprecated instead as removing these might break downstream clients.
- Major version change, may deprecate pieces or simply remove them given enough deprecation time.

## Deprecations

The spec allows for deprecations of:

#### Entire API:

```json
{
"api" : {
"documentation": "...",
"deprecated" : {
"version" : "7.0.0",
"description" : "Reason API is being deprecated"
},
}
}
```

#### Specific paths:

```json
{
"api": {
"documentation": "",
"url": {
"paths": ["/_monitoring/bulk"],
"deprecated_paths" : [
{
"version" : "7.0.0",
"path" : "/_monitoring/{type}/bulk",
"description" : "Specifying types in urls has been deprecated"
}
]
}
}
}
```

Here `paths` describes the preferred paths and `deprecated_paths` indicates `paths` that will still work but are now
deprecated.

#### Parameters

```json
{
"api": {
"documentation": "",
"methods": ["GET"],
"url": {
"params": {
"stored_fields": {
"type": "list",
"description" : "",
"deprecated" : {
"version" : "7.0.0",
"description" : "Reason parameter is being deprecated"
}
}
}
}
}
}
```

## License

This software is licensed under the Apache License, version 2 ("ALv2").