High level REST client parameters look wrong due indirectness and side effects #39666
Description
Using the high-level request client, this is how code to build a request with parameters appears today:
final Request request = new Request(HttpPut.METHOD_NAME, endpoint);
final RequestConverters.Params parameters = new RequestConverters.Params(request);
parameters.withWaitForActiveShards(putFollowRequest.waitForActiveShards());
request.setEntity(createEntity(putFollowRequest, REQUEST_BODY_CONTENT_TYPE));This looks wrong because parameters appears to be unused. That is, we create a RequestConverter.Params object, mutate it, and then it appears nothing happens to it. This code is not broken though, because what is happening behind the scenes is that request is being mutated when methods on parameters are invoked. This indirectness and methods having side effects on another object lead to code that does not appear correct at first glance, and is more confusing than it should be; it looks wrong. Instead, I propose an alternative like:
final Request request = new Request(HttpPut.METHOD_NAME, endpoint);
RequestConverters.Params parameters = new RequestConverters.Params();
parameters.withWaitForActiveShards(putFollowRequest.waitForActiveShards());
request.setParameters(parameters);
request.setEntity(createEntity(putFollowRequest, REQUEST_BODY_CONTENT_TYPE));This makes apparent that the parameters are actually used, and that they have an effect on the request object through explicit invocation. I believe this makes it more transparent what is occurring.