[ML] Calendars API : Inconsistencies in documentation / JSON spec

[codebrain]

The ml.getcalendars API has some issues:

1. It is not possible to use paging parameters (from/size) when addressing a single calendar_id in the request. Elasticsearch throws a request validation exception. This is unlike the behaviour of ml.getcategories which does allow this combination and returns an array with length 1.

2. The public documentation is incorrect (https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-calendar.html), the from and size parameters need to be nested under a parent page object as per the other ML APIs. It is also incomplete in that the description body parameter is not mentioned in any of the examples.

3. The YAML tests are misleading in that they do not use the page object prefix -

   elasticsearch/x-pack/plugin/src/test/resources/rest-api-spec/test/ml/calendar_crud.yml

   Line 116 in 9e8cfbb

   ml.get_calendars:

4. The absence of of a body description in the JSON spec:

   elasticsearch/x-pack/plugin/src/test/resources/rest-api-spec/api/ml.get_calendars.json

   Line 27 in 9e8cfbb

   "body": null

   - a null value instead signals our code generator to generate only GET verbs, despite the generator being aware of the POST verb. It is arguable that this is a weakness in our .NET client generator, so I have patched the JSON locally using our patching mechanism to fix.

[elasticmachine]

Pinging @elastic/ml-core

[sophiec20]

cc @lcawl for docs

[davidkyle]

I raised #39801 for points 2,3 & 4 above

It is not possible to use paging parameters (from/size) when addressing a single calendar_id in the request. Elasticsearch throws a request validation exception.

I think it makes sense that from/size are disallowed when an id is specified, that is the behaviour in the other ml apis I looked at where object id and from/size parameters may be used:

• GET Categories
• GET Calendars
• GET Filters
• GET Buckets

The exception is GET Model Snapshots which silently ignores the page params if a snapshot ID is set.

This is unlike the behaviour of ml.getcategories which does allow this combination and returns an array with length 1.

Looking at the code this isn't the case (on master at least). There is even a test to assert this combination of parameters is not allowed.

https://github.com/elastic/elasticsearch/blob/master/x-pack/plugin/src/test/resources/rest-api-spec/test/ml/jobs_get_result_categories.yml#L121