[ML] Correct small inconsistencies in ml APIs spec and docs

[davidkyle]

Closes #39677

• ml.get_calendars accepts POST requests with a body but in the rest spec body was null which makes the language clients think that is not the case.
• Correct the docs for ml.get_calendars using page parameters in the body.

Closes #39673 by registering the missing URL for delete forecast where the forecast id is not specified.
Closes #39676 with a doc change in eventresource.asciidoc.

[elasticmachine]

Pinging @elastic/ml-core

[droberts195]

I wonder if we're doing people a disservice by explicitly saying it's only milliseconds since the epoch. We accept times in the default format accepted by Elasticsearch, which is strict_date_optional_time||epoch_millis. This default is widely used but only documented in a half-arsed way, in https://www.elastic.co/guide/en/elasticsearch/reference/current/date.html.

I just looked at our other endpoint documentation and it often doesn't specify the format for times supplied as URL arguments. One that does is start datafeeds, and that uses a bulleted list separate to the parameter descriptions, but it does say that both epoch and ISO 8601 times are supported.

Anyway, I'd prefer that if we specify anything we make it clear that we're flexible, so I would change in milliseconds since the epoch to in milliseconds since the epoch or ISO 8601 format in both places.

[davidkyle]

Scheduled Events can be created with timestamps in either ISO 8601 or epoch millis, any view of the object will have the timestamps in epoch millis. I pushed a change for the POST _ml/calendars/<calendar_id>/events docs explaining the format options similar to the example you gave where it is the format of the API params that are documented rather than the resource fields.

[droberts195]

But now there's a discrepancy between the two files, as the POST _ml/calendars/<calendar_id>/events docs say the start and end time can be a string with epoch millis or ISO 8601, and then there's a cross reference to this file where the detailed docs say the type is long, which rules out ISO 8601. I think this file should also say both formats are possible and list the type as string.

[davidkyle]

The other ml resource objects use the date type for timestamps e.g. buckets https://www.elastic.co/guide/en/elasticsearch/reference/6.2/ml-results-resource.html#ml-results-buckets I changed the event resource docs to be the same.

The event can be created with a string but thereafter it will always be a long I think saying it is a string is just plain wrong as any API request will return the value a long.

[droberts195]

Yes, true, string would be wrong. date is good, because presumably it reacts to ?human, so date makes that clear.

[davidkyle]

human is tricky not least because it is scarcely mentioned in the docs but it also creates a new field suffixed with _string i.e. start_time_string is the human readable field. I guess it would break clients otherwise

[droberts195]

Yes, I wasn't suggesting we mention ?human in this doc, just that saying the field type is date makes it clearer that ?human will work for human clients. I would never expect the language clients to use ?human.

[lcawl]

Documentation LGTM

[droberts195]

LGTM