You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This is a meta issue to track completeness of the Java REST high-level Client in terms of supported API. The following list includes all the REST API that Elasticsearch exposes to date, and that are also exposed by the Transport Client. The ones marked as done are already supported by the high-level REST client, while the others need to be added. Every group is sorted based on an estimation around how important the API is, from more important to less important. Each API is also assigned a rank (easy, medium, hard) that expresses how difficult adding support for it is expected to be.
The API listed as "Not Required" won't need to be supported before the transport client is removed from the master branch (next major version). Such API are mainly administrative API that are not likely to be used from a Java application. They generally return heavy responses and make it hard to reuse response objects from the transport client as they expose internal objects that in some cases cannot even be parsed back entirely based on the information returned at REST. We considered returning those as maps of maps but that’s also easy to achieve using the low-level REST client hence we decided to not implement them for the time being.
search shards (medium) (exposes ShardRouting, DiscoveryNode and requires parsing back QueryBuilder)
pending cluster tasks (easy)
allocation explain (hard) (exposes ShardRouting)
cluster state (hard) (exposes ClusterState)
reroute (easy if done after cluster state API, returns the entire cluster state)
nodes info (hard) (exposes DiscoveryNode and a lot of other objects)
nodes stats (hard) (exposes ShardRouting and a lot of other objects)
cluster stats (hard) (exposes DiscoveryNode, requires nodes info and nodes stats)
hot threads (easy) (exposes DiscoveryNode)
nodes usage (medium) (exposes DiscoveryNode)
REST only API
There are a number of API that are exposed via REST but not via the Transport Client. They don't necessarily have to be implemented if the goal is feature parity with the Transport Client, yet we should probably have a look at why they were not added to the Transport Client and whether it makes sense to add their support to the high-level REST Client or not. I don't think it makes sense to add support for cat API and ingest processor grok, hence I took them out already.
add fromXContent method to existing response class currently used by transport client and corresponding unit tests that make use of fields shuffling as well as random fields insertion (in order to test forward compatibility). That usually means adding a test for the response object that extends AbstractXContentTestCase where supportsUnknownFields() returns true as well as assertToXContentEquivalence. There are cases where we can't insert random fields everywhere, which then require to also override the getRandomFieldsExcludeFilter() method which returns path that should be excluded when injecting random fields. Given the randomizations applied, it makes sense to run this type of test locally with -Dtests.iters=50 argument just to make sure that it is consistently green.
add new method to Request class which translates the input request into the internal REST request representation that holds method, url, endpoint, params etc. and add corresponding tests to RequestTests
add new method to RestHighLevelClient, possibly also its async variant when it makes sense, we may not want to add async variants to every single method, so we decide case by case. The name of the new method must match what is defined in our REST spec including the namespace.
add integration test that extends ESRestHighLevelClientTestCase that tests the new method end-to-end by sending REST requests to an external cluster.
add docs page. To check how docs are rendered and whether the links between docs pages and docs snippets work ok, run the following command from the root of your local checkout of the Elasticsearch repository: /path/to/elastic/docs/build_docs.pl --doc docs/java-rest/index.asciidoc --chunk 1 --out ~/temp/asciidoc --open . This requires also a local checkout of the docs repository, where the perl script is located.
This is a meta issue to track completeness of the Java REST high-level Client in terms of supported API. The following list includes all the REST API that Elasticsearch exposes to date, and that are also exposed by the Transport Client. The ones marked as done are already supported by the high-level REST client, while the others need to be added. Every group is sorted based on an estimation around how important the API is, from more important to less important. Each API is also assigned a rank (easy, medium, hard) that expresses how difficult adding support for it is expected to be.
The API listed as "Not Required" won't need to be supported before the transport client is removed from the master branch (next major version). Such API are mainly administrative API that are not likely to be used from a Java application. They generally return heavy responses and make it hard to reuse response objects from the transport client as they expose internal objects that in some cases cannot even be parsed back entirely based on the information returned at REST. We considered returning those as maps of maps but that’s also easy to achieve using the low-level REST client hence we decided to not implement them for the time being.
Top-level APIs
Indices API
[ ] types exist (easy)Not required
Snapshot API
Ingest API
Tasks API
Cluster API
Not required
REST only API
There are a number of API that are exposed via REST but not via the Transport Client. They don't necessarily have to be implemented if the goal is feature parity with the Transport Client, yet we should probably have a look at why they were not added to the Transport Client and whether it makes sense to add their support to the high-level REST Client or not. I don't think it makes sense to add support for cat API and ingest processor grok, hence I took them out already.
ingest processor grokcat API: aliases, allocation, count, fielddata, health, help, indices, master, nodeattrs, nodes, pending tasks, plugins, recovery, repositories, segments, shards, snapshots, tasks, templates, threadpoolHow to add support for a new API
Look at some of the already supported API and existing PRs that have been merged:
The common tasks in each of the above PRs are:
fromXContentmethod to existing response class currently used by transport client and corresponding unit tests that make use of fields shuffling as well as random fields insertion (in order to test forward compatibility). That usually means adding a test for the response object that extendsAbstractXContentTestCasewheresupportsUnknownFields()returns true as well asassertToXContentEquivalence. There are cases where we can't insert random fields everywhere, which then require to also override thegetRandomFieldsExcludeFilter()method which returns path that should be excluded when injecting random fields. Given the randomizations applied, it makes sense to run this type of test locally with-Dtests.iters=50argument just to make sure that it is consistently green.Requestclass which translates the input request into the internal REST request representation that holds method, url, endpoint, params etc. and add corresponding tests toRequestTestsRestHighLevelClient, possibly also its async variant when it makes sense, we may not want to add async variants to every single method, so we decide case by case. The name of the new method must match what is defined in our REST spec including the namespace.ESRestHighLevelClientTestCasethat tests the new method end-to-end by sending REST requests to an external cluster./path/to/elastic/docs/build_docs.pl --doc docs/java-rest/index.asciidoc --chunk 1 --out ~/temp/asciidoc --open. This requires also a local checkout of the docs repository, where the perl script is located.Relates #29827