Fix inconsistencies in the rest api specs for tasks

[olcbean]

Modify parameters names to bring the tasks rest-api-specup to date with the code base.

Fixes #27124

[elasticmachine]

Since this is a community submitted pull request, a Jenkins build has not been kicked off automatically. Can an Elastic organization member please verify the contents of this patch and then kick off a build manually?

[javanna]

hi @olcbean thanks for your PR, and good catch! I wonder if there's a way to add a test that uses these two parameters, that would have been the only way to catch this naming issue. Do you have any idea?

[olcbean]

@javanna I am not sure that adding tests specifically for these params would be worthwhile, as the tests would be rather naive: just verifying that there is no exception. Only for these two parameters.

I really think that a more comprehensive approach should be considered. What about trying to validate the rest-api-apecs by sending numerous REST requests and monitor the exceptions that are returned. Such requests can be generated following the rest-api-specs.

I would be interested to work on this and believe that in a couple of weeks I should have something usable.

I am thinking to cover (at least) the following scenarios :

• attempt to remove any required path part - expected exception that the corresponding path part cannot be removed (IllegalArgumentException : "unable to find matching rest path for api")
• attempt to remove a required parameter : an exception is expected
• attempt to fire a request with every single optional parameter : no exception (IllegalArgumentException : "unrecognized parameter")
• if the request does not expect a body, but a body is supplied : exception is thrown (currently not the case?) <-- maybe this should be skipped?
• if a required body is removed an exception is thrown (ElasticsearchParseException : "request body is required")
• if an optional body is not present : no exception is thrown

My first thought would be to do this in ESClientYamlSuiteTestCase#initAndResetContext so that we know that the base for the REST tests is correct.

Currently there is no comprehensive rest-api-spec parser. One would be necessary as the types of parameters being tested need to be known ahead of time, so that valid values are submitted as part of the test. I can extend the existing one or maybe there is a client code which can be reused ( if there is - pointers would be much appreciated as this will save quite some effort ).

Let me know what you think!

[javanna]

hey @olcbean thanks for your proposal. We historically relied on test failures to notify us of problems in the spec. I do see that this approach has limitations and doesn't give us full coverage. On the other hand, what you propose sounds like quite some work on something that will be obsolete once we generate the spec from the server code like @jasontedor mentioned in #27158 . It is not too easy to judge whether what you propose is worth the effort or not. I tend to think it is not at the moment. @elastic/es-clients thoughts on this?

[jasontedor]

It is not too easy to judge whether what you propose is worth effort or not. I tend to think it is not at the moment.

I appreciate the proposal and the offer but I agree with @javanna here.

[Mpdreamz]

Agreed as well, having the spec being generated sounds like equal amount the work and be more beneficial as a first step. Fuzzing the rest API spec afterwards could definitely proof useful 👍

[olcbean]

@javanna I agree that such an approach is an overkill for only four parameters in 2 apis. But currently there are at least 29 (out of 118) apis referring to at least 94 incorrect parameter names.

Generating the rest-api-specs based on the code base is definitely a better and more comprehensive approach, but AFAIK it is currently not on the radar.

[honzakral]

@javanna my thoughts are that we have been talking about generating the spec from code for over 4 years now ever since @karmi created the first draft by parsing the java code. Do we have a timeline for this, issue to track it, champion to develop this?

I would love for this to happen as we struggle with this every time a new version is released, but with all of the things going on I am a bit worried it would fall through the cracks again.

[javanna]

thanks @olcbean I just merged this.