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.

Sign up for GitHub

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

[DOCS] Adds information about version compatibility headers #77096

Merged
merged 5 commits into from
Sep 3, 2021
Merged

[DOCS] Adds information about version compatibility headers #77096

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
606f838
[DOCS] Adds information about version compatibility
debadair Sep 1, 2021
9061c03
Clarified that the behavior is not guaranteed to be the same
debadair Sep 1, 2021
6a84576
Update docs/reference/api-conventions.asciidoc
debadair Sep 2, 2021
f0436bd
Update docs/reference/api-conventions.asciidoc
debadair Sep 3, 2021
6e80419
Update docs/reference/api-conventions.asciidoc
debadair Sep 3, 2021
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
28 changes: 28 additions & 0 deletions docs/reference/api-conventions.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -214,6 +214,34 @@ instead. When using this method, the `source_content_type` parameter
should also be passed with a media type value that indicates the format
of the source, such as `application/json`.

[discrete]
[[api-compatibility]]
=== REST API version compatibility

Major version upgrades often include a number of breaking changes
that impact how you interact with {es}.
While we recommend that you monitor the deprecation log and
update applications before upgrading {es},
having to coordinate the necessary changes can be an impediment to upgrading.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
having to coordinate the necessary changes can be an impediment to upgrading.
implementing the necessary changes can be an impediment to upgrading.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"having to coordinate" feels imprecise, thought that might be the intention given that we're talking about all the things that need to happen for an upgrade.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It was deliberate. Using the compatibility headers enables you to decouple the implementation and deployment of app updates from the upgrade process.


To enable an application to continue to function without modification after an upgrade,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should be more clear the functionality (semantics) are not necessarily maintained, the compatibility is with the syntax of rest request/response.

you can include API compatibility headers that tell {es} that
you are still using the previous version of the REST API.
You set version compatibility on a per-request basis in the `Content-Type` and `Accept` headers.

Setting `compatible-with` to the same major version as
the version you're running has no impact,
but ensures that the request will still work after {es} is upgraded.

To tell {es} 8.0 you are using the 7.x request and response format,
set `compatible-with=7`:

[source,sh]
----------------------------------------------------------------------
Content-Type: application/vnd.elasticsearch+json; compatible-with=7
Accept: application/vnd.elasticsearch+json; compatible-with=7
----------------------------------------------------------------------

[discrete]
[[api-url-access-control]]
=== URL-based access control
Expand Down