[DOCS] Added ML calendar APIs (elastic/x-pack-elasticsearch#3328)

* [DOCS] Added ML calendar APIs

* [DOCS] Updated calendar job API titles

* [DOCS] Added more calendar APIs

Original commit: elastic/x-pack-elasticsearch@0910da09eb

docs/en/rest-api/ml-api.asciidoc

@@ -6,6 +6,14 @@ You can use the following APIs to perform {ml} activities.
 See <<ml-api-definitions, Definitions>> for the resource definitions used by the
 machine learning APIs and in advanced job configuration options in Kibana.
 
+[float]
+[[ml-api-calendar-endpoint]]
+=== Calendars
+
+* <<ml-put-calendar,Create calendar>>, <<ml-delete-calendar,Delete calendar>>
+* <<ml-put-calendar-job,Add job to calendar>>, <<ml-delete-calendar-job,Delete job from calendar>>
+* <<ml-get-calendar,Get calendars>>
+
 [float]
 [[ml-api-datafeed-endpoint]]
 === {dfeeds-cap}
@@ -24,6 +32,7 @@ machine learning APIs and in advanced job configuration options in Kibana.
 
 //* <<ml-valid-detector,Validate detectors>>, <<ml-valid-job,Validate job>>
 * <<ml-put-job,Create job>>, <<ml-delete-job,Delete job>>
+* <<ml-put-calendar-job,Add job to calendar>>, <<ml-delete-calendar-job,Delete job from calendar>>
 * <<ml-open-job,Open job>>, <<ml-close-job,Close job>>
 * <<ml-get-job,Get job info>>, <<ml-get-job-stats,Get job statistics>>
 * <<ml-flush-job,Flush job>>
@@ -51,21 +60,26 @@ machine learning APIs and in advanced job configuration options in Kibana.
 * <<ml-get-influencer,Get influencers>>
 * <<ml-get-record,Get records>>
 
-
+//ADD
+include::ml/put-calendar-job.asciidoc[]
 //CLOSE
 include::ml/close-job.asciidoc[]
 //CREATE
+include::ml/put-calendar.asciidoc[]
 include::ml/put-datafeed.asciidoc[]
 include::ml/put-job.asciidoc[]
 //DELETE
+include::ml/delete-calendar.asciidoc[]
 include::ml/delete-datafeed.asciidoc[]
 include::ml/delete-job.asciidoc[]
+include::ml/delete-calendar-job.asciidoc[]
 include::ml/delete-snapshot.asciidoc[]
 //FLUSH
 include::ml/flush-job.asciidoc[]
 //FORECAST
 include::ml/forecast.asciidoc[]
 //GET
+include::ml/get-calendar.asciidoc[]
 include::ml/get-bucket.asciidoc[]
 include::ml/get-overall-buckets.asciidoc[]
 include::ml/get-category.asciidoc[]

docs/en/rest-api/ml/delete-calendar-job.asciidoc

@@ -0,0 +1,35 @@
+[role="xpack"]
+[[ml-delete-calendar-job]]
+=== Delete Jobs from Calendar API
+++++
+<titleabbrev>Delete Jobs from Calendar</titleabbrev>
+++++
+
+The delete jobs from calendar API enables you to remove jobs from a calendar.
+
+
+==== Request
+
+`DELETE _xpack/ml/calendars/<calendar_id>/jobs/<job_id>`
+
+
+//==== Description
+
+
+==== Path Parameters
+
+`calendar_id`(required)::
+  (string) Identifier for the calendar.
+
+`job_id` (required)::
+  (string) Identifier for the job.
+
+//===== Query Parameters
+
+
+==== Authorization
+
+You must have `manage_ml`, or `manage` cluster privileges to use this API.
+For more information, see {xpack-ref}/security-privileges.html[Security Privileges].
+
+//==== Examples

docs/en/rest-api/ml/delete-calendar.asciidoc

@@ -0,0 +1,27 @@
+[role="xpack"]
+[[ml-delete-calendar]]
+=== Delete Calendars
+
+The delete calendar API enables you to delete a calendar.
+
+
+==== Request
+
+`DELETE _xpack/ml/calendars/<calendar_id>`
+
+
+//==== Description
+
+==== Path Parameters
+
+`calendar_id` (required)::
+  (string) Identifier for the calendar.
+
+//===== Query Parameters
+
+==== Authorization
+
+You must have `manage_ml`, or `manage` cluster privileges to use this API.
+For more information, see {xpack-ref}/security-privileges.html[Security Privileges].
+
+//==== Examples

docs/en/rest-api/ml/get-calendar.asciidoc

@@ -0,0 +1,62 @@
+[role="xpack"]
+[[ml-get-calendar]]
+=== Get Calendars
+
+The get calendars API enables you to retrieve configuration information for
+calendars.
+
+
+==== Request
+
+`GET _xpack/ml/calendars/<calendar_id>` +
+
+`GET _xpack/ml/calendars/<calendar_id>,<calendar_id>` +
+
+`GET _xpack/ml/calendars/` +
+
+`GET _xpack/ml/calendars/_all`
+
+
+//===== Description
+
+////
+You can get information for multiple jobs in a single API request by using a
+group name, a comma-separated list of jobs, or a wildcard expression. You can
+get information for all jobs by using `_all`, by specifying `*` as the
+`<job_id>`, or by omitting the `<job_id>`.
+////
+
+==== Path Parameters
+
+`calendar_id`::
+  (string) Identifier for the calendar. It can be a calendar identifier or a
+  wildcard expression. If you do not specify one of these options, the API
+  returns information for all calendars.
+
+
+==== Request Body
+
+`from`:::
+    (integer) Skips the specified number of calendars.
+
+`size`:::
+    (integer) Specifies the maximum number of calendars to obtain.
+
+//==== Results
+
+////
+The API returns the following information:
+
+`jobs`::
+  (array) An array of job resources.
+  For more information, see <<ml-job-resource,Job Resources>>.
+////
+
+==== Authorization
+
+You must have `monitor_ml`, `monitor`, `manage_ml`, or `manage` cluster
+privileges to use this API. For more information, see
+{xpack-ref}/security-privileges.html[Security Privileges].
+
+
+//==== Examples

docs/en/rest-api/ml/put-calendar-job.asciidoc

@@ -0,0 +1,34 @@
+[role="xpack"]
+[[ml-put-calendar-job]]
+=== Add Jobs to Calendar API
+++++
+<titleabbrev>Add Jobs to Calendar</titleabbrev>
+++++
+
+The add jobs to calendar API enables you to remove jobs from a calendar.
+
+==== Request
+
+`PUT _xpack/ml/calendars/<calendar_id>/jobs/<job_id>`
+
+//===== Description
+
+==== Path Parameters
+
+`calendar_id` (required)::
+  (string) Identifier for the calendar.
+
+`job_id` (required)::
+  (string) Identifier for the job.
+
+
+//==== Request Body
+
+==== Authorization
+
+You must have `manage_ml`, or `manage` cluster privileges to use this API.
+For more information, see
+{xpack-ref}/security-privileges.html[Security Privileges].
+
+
+//==== Examples

docs/en/rest-api/ml/put-calendar.asciidoc

@@ -0,0 +1,32 @@
+[role="xpack"]
+[[ml-put-calendar]]
+=== Create Calendars
+
+The create calendar API enables you to instantiate a calendar.
+
+==== Request
+
+`PUT _xpack/ml/calendars/<calendar_id>`
+
+//===== Description
+
+==== Path Parameters
+
+`calendar_id` (required)::
+  (string) Identifier for the calendar.
+
+
+==== Request Body
+
+`description`::
+  (string) A description of the calendar.
+
+==== Authorization
+
+You must have `manage_ml`, or `manage` cluster privileges to use this API.
+For more information, see
+{xpack-ref}/security-privileges.html[Security Privileges].
+
+
+//==== Examples
+//See plugin/src/test/resources/rest-api-spec/test/ml/calendar_crud.yml