Elastic APIs versioning and usage without breaking the integrated services

hi Team, we have few queries on Elasticserach APIs:

  1. Suppose we have used an API in our code and there is a version upgrade. How to handle the version change ? Will it not break our code integration with this API ? (If there are any minor changes like adding a new parameter might not have change, but if there is a major change in the API, this would break our code as well).
  2. Is there any way that we can use a particular version of the API and this will not have any impact on the version upgrades ?
  3. We have open source APIs in our code, are there any possibilities that an open source API being converted to x-pack, which then would lead to a service break.
    Request your assistance here. Thanks.

Breaking changes to APIs are flagged in advance with deprecation warnings whenever you use them. Before performing a major version upgrade you should upgrade to the latest release of the previous major version, and then verify that your client is not generating any deprecation logs. Having done that you can be confident that you won't be affected by any breaking changes.

Breaking changes to APIs within a major version are something we avoid.

I don't think this has ever happened and if it did it would be in truly exceptional circumstances. If it happened it'd also be considered a breaking change so the same rules apply: only at a major version upgrade and signalled in advance by deprecation logs.

Hi David, Thanks a lot for your reply. Adding the deprecation logs is a good approach.

But I still have my 2nd question : Is there any way that we can use a particular version of the API and this will not have any impact on the version upgrades ? : Is it possible to use the elastic API of a particular version and stick to it, even though there would be version upgrades e.g: we stick to v7.10 and not change it.
Is it possible to specify explicitly the API with version, like passing in the API - URI or query string parameters or in the payload.

Also how many days before we get the intimation for the next breaking changes list/ the deprecation logs gets enabled, so that we have some buffer to work on our services which would have integrated with this elastic APIs.

Request for your assistance. Thanks in advance.

No, not if you want to upgrade to an 8.x version. That said, the 7.10 API will work throughout the rest of the 7.x series, which will be supported until the release of 9.0. That's a very long way off, you will have ample time to adjust to any deprecations.

The deprecation logs are always enabled, and you are in control of upgrades so you can delay the upgrade for as long as you need.

Thanks for the reply David.
One simple question, How do I know which version of the API it is pointing to.
say for e.g: We take Search API : GET index_name/_search,
which version is it referring to in elastic and getting us the response.

As you mentioned : The deprecation logs are always enabled, and you are in control of upgrades so you can delay the upgrade for as long as you need.

I didnt get your point fully, could you please explain a bit more on this.

  • Can we delay the elastic API upgrade as you are mentioning ? that might not be possible as elastic API would have been upgraded from your end, which might break our services.
  • If we can delay, then How can we delay the upgrade as we dont have the control over the elastic APIs ?
  • How do we handle this upgradation of elastic APIs in our java based integrated services.

Request you to assist us more on this versioning. Please share the docs if you have any, that would be of a great help. Thanks.

By "your end" do you mean Elastic Cloud? If so, no, we don't do any upgrades unless you tell us to.

GET / returns the version of the responding node, amongst other things.

Thanks David. Will get back for further queries.

This topic was automatically closed 28 days after the last reply. New replies are no longer allowed.