[DOCS] Added ML add and delete calendar event APIs (elastic/x-pack-elasticsearch#3394)

Original commit: elastic/x-pack-elasticsearch@3283af2215

docs/build.gradle

@@ -23,6 +23,7 @@ buildRestTests.expectedUnconvertedCandidates = [
         'en/rest-api/security/users.asciidoc',
         'en/rest-api/security/tokens.asciidoc',
         'en/rest-api/watcher/put-watch.asciidoc',
+        'en/rest-api/ml/delete-calendar-event.asciidoc',
         'en/rest-api/ml/post-data.asciidoc',
         'en/security/authentication/user-cache.asciidoc',
         'en/security/authorization/field-and-document-access-control.asciidoc',
@@ -351,5 +352,43 @@ setups['server_metrics_startdf'] = '''
   - do:
       xpack.ml.start_datafeed:
         datafeed_id: "datafeed-total-requests"
+'''
+setups['calendar_outages'] = '''
+  - do:
+        xpack.ml.put_calendar:
+          calendar_id: "planned-outages"
+'''
+setups['calendar_outages_addevent'] = setups['calendar_outages'] + '''
+  - do:
+        xpack.ml.post_calendar_events:
+          calendar_id: "planned-outages"
+          body: >
+            { "description": "event 1", "start_time": "2017-12-01T00:00:00Z", "end_time": "2017-12-02T00:00:00Z", "calendar_id": "planned-outages" }
+
 
 '''
+setups['calendar_outages_openjob'] = setups['server_metrics_openjob'] + '''
+  - do:
+       xpack.ml.put_calendar:
+         calendar_id: "planned-outages"
+'''
+setups['calendar_outages_addjob'] = setups['server_metrics_openjob'] + '''
+  - do:
+       xpack.ml.put_calendar:
+         calendar_id: "planned-outages"
+         body:  >
+           {
+           "job_ids": ["total-requests"]
+           }
+'''
+setups['calendar_outages_addevent'] = setups['calendar_outages_addjob'] + '''
+  - do:
+       xpack.ml.post_calendar_events:
+         calendar_id: "planned-outages"
+         body:  >
+           { "events" : [
+           { "description": "event 1", "start_time": "1513641600000", "end_time": "1513728000000"},
+           { "description": "event 2", "start_time": "1513814400000", "end_time": "1513900800000"},
+           { "description": "event 3", "start_time": "1514160000000", "end_time": "1514246400000"}
+           ]}
+'''

docs/en/ml/api-quickref.asciidoc

@@ -32,6 +32,19 @@ The main {ml} resources can be accessed with a variety of endpoints:
 * {ref}/ml-close-job.html[POST /anomaly_detectors/<job_id>/_close]: Close a job
 * {ref}/ml-delete-job.html[DELETE /anomaly_detectors/<job_id+++>+++]: Delete a job
 
+[float]
+[[ml-api-calendars]]
+=== /calendars/
+
+* {ref}/ml-put-calendar.html[PUT /calendars/<calendar_id+++>+++]: Create a calendar
+* {ref}/ml-post-calendar-event.html[POST /calendars/<calendar_id+++>+++/events]: Add a scheduled event to a calendar
+* {ref}/ml-put-calendar-job.html[PUT /calendars/<calendar_id+++>+++/jobs/<job_id+++>+++]: Associate a job with a calendar
+* {ref}/ml-get-calendar.html[GET /calendars/<calendar_id+++>+++]: Get calendar details
+* {ref}/ml-get-calendar-event.html[GET /calendars/<calendar_id+++>+++/events]: Get scheduled event details
+* {ref}/ml-delete-calendar-event.html[DELETE /calendars/<calendar_id+++>+++/events/<event_id+++>+++]: Remove a scheduled event from a calendar
+* {ref}/ml-delete-calendar-job.html[DELETE /calendars/<calendar_id+++>+++/jobs/<job_id+++>+++]: Disassociate a job from a calendar
+* {ref}/ml-delete-calendar.html[DELETE /calendars/<calendar_id+++>+++]: Delete a calendar
+
 [float]
 [[ml-api-datafeeds]]
 === /datafeeds/

docs/en/ml/calendars.asciidoc

@@ -21,10 +21,7 @@ events appropriately.
 
 If you want to add multiple scheduled events at once, you can import an
 iCalendar (`.ics`) file in {kib} or a JSON file in the
-//{ref}/ml-post-calendar-event.html[
-add events to calendar API
-//]
-.
+{ref}/ml-post-calendar-event.html[add events to calendar API].
 
 [NOTE]
 --

docs/en/rest-api/defs.asciidoc

@@ -5,13 +5,17 @@
 These resource definitions are used in {ml} APIs and in {kib} advanced
 job configuration options.
 
+* <<ml-calendar-resource,Calendars>>
 * <<ml-datafeed-resource,{dfeeds-cap}>>
 * <<ml-datafeed-counts,{dfeed-cap} counts>>
 * <<ml-job-resource,Jobs>>
 * <<ml-jobstats,Job statistics>>
 * <<ml-snapshot-resource,Model snapshots>>
 * <<ml-results-resource,Results>>
+* <<ml-event-resource,Scheduled Events>>
 
+[role="xpack"]
+include::ml/calendarresource.asciidoc[]
 [role="xpack"]
 include::ml/datafeedresource.asciidoc[]
 [role="xpack"]
@@ -22,3 +26,5 @@ include::ml/jobcounts.asciidoc[]
 include::ml/snapshotresource.asciidoc[]
 [role="xpack"]
 include::ml/resultsresource.asciidoc[]
+[role="xpack"]
+include::ml/eventresource.asciidoc[]

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

@@ -12,7 +12,8 @@ machine learning APIs and in advanced job configuration options in Kibana.
 
 * <<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>>
+* <<ml-post-calendar-event,Add scheduled events to calendar>>, <<ml-delete-calendar-event,Delete scheduled events from calendar>>
+* <<ml-get-calendar,Get calendars>>, <<ml-get-calendar-event,Get scheduled events>>
 
 [float]
 [[ml-api-datafeed-endpoint]]
@@ -61,6 +62,7 @@ machine learning APIs and in advanced job configuration options in Kibana.
 * <<ml-get-record,Get records>>
 
 //ADD
+include::ml/post-calendar-event.asciidoc[]
 include::ml/put-calendar-job.asciidoc[]
 //CLOSE
 include::ml/close-job.asciidoc[]
@@ -71,6 +73,7 @@ include::ml/put-job.asciidoc[]
 //DELETE
 include::ml/delete-calendar.asciidoc[]
 include::ml/delete-datafeed.asciidoc[]
+include::ml/delete-calendar-event.asciidoc[]
 include::ml/delete-job.asciidoc[]
 include::ml/delete-calendar-job.asciidoc[]
 include::ml/delete-snapshot.asciidoc[]
@@ -89,6 +92,7 @@ include::ml/get-influencer.asciidoc[]
 include::ml/get-job.asciidoc[]
 include::ml/get-job-stats.asciidoc[]
 include::ml/get-snapshot.asciidoc[]
+include::ml/get-calendar-event.asciidoc[]
 include::ml/get-record.asciidoc[]
 //OPEN
 include::ml/open-job.asciidoc[]

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

@@ -0,0 +1,14 @@
+[role="xpack"]
+[[ml-calendar-resource]]
+=== Calendar Resources
+
+A calendar resource has the following properties:
+
+`calendar_id`::
+  (string) A numerical character string that uniquely identifies the calendar.
+
+`job_ids`::
+  (array) An array of job identifiers. For example: `["total-requests"]`.
+
+For more information, see 
+{xpack-ref}/ml-calendars.html[Calendars and Scheduled Events].

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

@@ -0,0 +1,55 @@
+[role="xpack"]
+[[ml-delete-calendar-event]]
+=== Delete Events from Calendar API
+++++
+<titleabbrev>Delete Events from Calendar</titleabbrev>
+++++
+
+This API enables you to delete scheduled events from a calendar.
+
+
+==== Request
+
+`DELETE _xpack/ml/calendars/<calendar_id>/events/<event_id>`
+
+
+==== Description
+
+This API removes individual events from a calendar. To remove all scheduled
+events and delete the calendar, see the
+<<ml-delete-calendar,delete calendar API>>.
+
+==== Path Parameters
+
+`calendar_id`(required)::
+  (string) Identifier for the calendar.
+
+`event_id` (required)::
+  (string) Identifier for the scheduled event. You can obtain this identifier
+  by using the <<ml-get-calendar-event,get calendar events API>>.
+
+
+==== 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
+
+The following example deletes a scheduled event from the `planned-outages`
+calendar:
+
+[source,js]
+--------------------------------------------------
+DELETE _xpack/ml/calendars/planned-outages/events/LS8LJGEBMTCMA-qz49st
+--------------------------------------------------
+// CONSOLE
+// TEST[skip:automatically-generated ID]
+
+When the event is removed, you receive the following results:
+[source,js]
+----
+{
+  "acknowledged": true
+}
+----

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

@@ -5,7 +5,7 @@
 <titleabbrev>Delete Jobs from Calendar</titleabbrev>
 ++++
 
-This API enables you to remove jobs from a calendar.
+This API enables you to delete jobs from a calendar.
 
 
 ==== Request
@@ -13,9 +13,6 @@ This API enables you to remove jobs from a calendar.
 `DELETE _xpack/ml/calendars/<calendar_id>/jobs/<job_id>`
 
 
-//==== Description
-
-
 ==== Path Parameters
 
 `calendar_id`(required)::
@@ -24,12 +21,32 @@ This API enables you to remove jobs from a 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
+==== Examples
+
+The following example removes the association between the `planned-outages`
+calendar and `total-requests` job:
+
+[source,js]
+--------------------------------------------------
+DELETE _xpack/ml/calendars/planned-outages/jobs/total-requests
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:calendar_outages_addjob]
+
+When the job is removed from the calendar, you receive the following
+results:
+
+[source,js]
+----
+{
+   "calendar_id": "planned-outages",
+   "job_ids": []
+}
+----
+//TESTRESPONSE

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

@@ -13,18 +13,40 @@ This API enables you to delete a calendar.
 `DELETE _xpack/ml/calendars/<calendar_id>`
 
 
-//==== Description
+==== Description
+
+This API removes all scheduled events from the calendar then deletes the
+calendar.
+
 
 ==== 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
+
+==== Examples
+
+The following example deletes the `planned-outages` calendar:
+
+[source,js]
+--------------------------------------------------
+DELETE _xpack/ml/calendars/planned-outages
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:calendar_outages]
+
+When the calendar is deleted, you receive the following results:
+[source,js]
+----
+{
+  "acknowledged": true
+}
+----
+//TESTRESPONSE

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

@@ -0,0 +1,26 @@
+[role="xpack"]
+[[ml-event-resource]]
+=== Scheduled Event Resources
+
+An events resource has the following properties:
+
+`calendar_id`::
+  (string) An identifier for the calendar that contains the scheduled
+  event. This property is optional in the <<ml-post-calendar-event>>. 
+
+`description`::
+  (string) A description of the scheduled event.
+
+`end_time`::
+  (string) The timestamp for the end of the scheduled event. The datetime string
+  is in ISO 8601 format.
+
+`event_id`::
+  (string) An automatically-generated identifier for the scheduled event.
+
+`start_time`::
+ (string) The timestamp for the beginning of the scheduled event. The datetime
+ string is in ISO 8601 format.
+
+For more information, see
+{xpack-ref}/ml-calendars.html[Calendars and Scheduled Events].

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

@@ -0,0 +1,106 @@
+[role="xpack"]
+[[ml-get-calendar-event]]
+=== Get Scheduled Events API
+++++
+<titleabbrev>Get Scheduled Events</titleabbrev>
+++++
+
+This API enables you to retrieve information about the scheduled events in
+calendars.
+
+
+==== Request
+
+`GET _xpack/ml/calendars/<calendar_id>/events` +
+
+`GET _xpack/ml/calendars/_all/events`
+
+
+===== Description
+
+You can get scheduled event information for a single calendar or for all
+calendars by using `_all`.
+
+==== Path Parameters
+
+`calendar_id` (required)::
+  (string) Identifier for the calendar.
+
+==== Request Body
+
+`end`::
+    (string) Specifies to get events with timestamps earlier than this time.
+
+`from`::
+    (integer) Skips the specified number of events.
+
+`size`::
+    (integer) Specifies the maximum number of events to obtain.
+
+`start`::
+    (string) Specifies to get events with timestamps after this time.
+
+==== Results
+
+The API returns the following information:
+
+`events`::
+  (array) An array of scheduled event resources.
+  For more information, see <<ml-event-resource>>.
+
+
+==== 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
+
+The following example gets information about the scheduled events in the
+`planned-outages` calendar:
+
+[source,js]
+--------------------------------------------------
+GET _xpack/ml/calendars/planned-outages/events
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:calendar_outages_addevent]
+
+The API returns the following results:
+
+[source,js]
+----
+{
+  "count": 3,
+  "events": [
+    {
+      "description": "event 1",
+      "start_time": 1513641600000,
+      "end_time": 1513728000000,
+      "calendar_id": "planned-outages",
+      "event_id": "LS8LJGEBMTCMA-qz49st"
+    },
+    {
+      "description": "event 2",
+      "start_time": 1513814400000,
+      "end_time": 1513900800000,
+      "calendar_id": "planned-outages",
+      "event_id": "Li8LJGEBMTCMA-qz49st"
+    },
+    {
+      "description": "event 3",
+      "start_time": 1514160000000,
+      "end_time": 1514246400000,
+      "calendar_id": "planned-outages",
+      "event_id": "Ly8LJGEBMTCMA-qz49st"
+    }
+  ]
+}
+----
+// TESTRESPONSE[s/LS8LJGEBMTCMA-qz49st/$body.$_path/]
+// TESTRESPONSE[s/Li8LJGEBMTCMA-qz49st/$body.$_path/]
+// TESTRESPONSE[s/Ly8LJGEBMTCMA-qz49st/$body.$_path/]
+
+For more information about these properties, see <<ml-event-resource>>.

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

@@ -5,36 +5,26 @@
 <titleabbrev>Get Calendars</titleabbrev>
 ++++
 
-This API enables you to retrieve configuration information for
-calendars.
+This 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
+===== Description
+
+You can get information for a single calendar or for all calendars by using
+`_all`.
 
-////
-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.
+  (string) Identifier for the calendar.
 
 
 ==== Request Body
@@ -45,15 +35,15 @@ get information for all jobs by using `_all`, by specifying `*` as the
 `size`:::
     (integer) Specifies the maximum number of calendars to obtain.
 
-//==== Results
 
-////
+==== Results
+
 The API returns the following information:
 
-`jobs`::
-  (array) An array of job resources.
-  For more information, see <<ml-job-resource,Job Resources>>.
-////
+`calendars`::
+  (array) An array of calendar resources.
+  For more information, see <<ml-calendar-resource>>.
+
 
 ==== Authorization
 
@@ -62,4 +52,31 @@ privileges to use this API. For more information, see
 {xpack-ref}/security-privileges.html[Security Privileges].
 
 
-//==== Examples
+==== Examples
+
+The following example gets configuration information for the `planned-outages`
+calendar:
+
+[source,js]
+--------------------------------------------------
+GET _xpack/ml/calendars/planned-outages
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:calendar_outages_addjob]
+
+The API returns the following results:
+[source,js]
+----
+{
+  "count": 1,
+  "calendars": [
+    {
+      "calendar_id": "planned-outages",
+      "job_ids": [
+        "total-requests"
+      ]
+    }
+  ]
+}
+----
+//TESTRESPONSE

docs/en/rest-api/ml/post-calendar-event.asciidoc

@@ -0,0 +1,87 @@
+[role="xpack"]
+[[ml-post-calendar-event]]
+=== Add Events to Calendar API
+++++
+<titleabbrev>Add Events to Calendar</titleabbrev>
+++++
+
+This API enables you to post scheduled events in a calendar.
+
+==== Request
+
+`POST _xpack/ml/calendars/<calendar_id>/events`
+
+
+==== Description
+
+This API accepts a list of {xpack-ref}/ml-calendars.html[scheduled events], each
+of which must have a start time, end time, and description.
+
+==== Path Parameters
+
+`calendar_id` (required)::
+		(string) Identifier for the calendar.
+
+
+==== Request Body
+
+`events`::
+  (array) A list of one of more scheduled events. See <<ml-event-resource>>.
+
+
+==== 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
+
+You can add scheduled events to the `planned-outages` calendar as follows:
+
+[source,js]
+--------------------------------------------------
+POST _xpack/ml/calendars/planned-outages/events
+{
+  "events" : [
+    {"description": "event 1", "start_time": 1513641600000, "end_time": 1513728000000},
+    {"description": "event 2", "start_time": 1513814400000, "end_time": 1513900800000},
+    {"description": "event 3", "start_time": 1514160000000, "end_time": 1514246400000}
+  ]
+}
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:calendar_outages_addjob]
+
+The API returns the following results:
+
+[source,js]
+----
+{
+  "events": [
+    {
+      "description": "event 1",
+      "start_time": 1513641600000,
+      "end_time": 1513728000000,
+      "calendar_id": "planned-outages"
+    },
+    {
+      "description": "event 2",
+      "start_time": 1513814400000,
+      "end_time": 1513900800000,
+      "calendar_id": "planned-outages"
+    },
+    {
+      "description": "event 3",
+      "start_time": 1514160000000,
+      "end_time": 1514246400000,
+      "calendar_id": "planned-outages"
+    }
+  ]
+}
+----
+//TESTRESPONSE
+
+For more information about these properties, see
+<<ml-event-resource,Scheduled Event Resources>>.

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

@@ -5,26 +5,21 @@
 <titleabbrev>Add Jobs to Calendar</titleabbrev>
 ++++
 
-This API enables you to add jobs to a calendar.
+This API enables you to add a job to a calendar.
 
 ==== Request
 
 `PUT _xpack/ml/calendars/<calendar_id>/jobs/<job_id>`
 
-//===== Description
 
 ==== Path Parameters
 
 `calendar_id` (required)::
   (string) Identifier for the calendar.
 
-//==== Request Body
-
 `job_id` (required)::
   (string) Identifier for the job.
 
-`description`::
-  (string) A description of the calendar.
 
 ==== Authorization
 
@@ -33,4 +28,27 @@ For more information, see
 {xpack-ref}/security-privileges.html[Security Privileges].
 
 
-//==== Examples
+==== Examples
+
+The following example associates the `planned-outages` calendar with the
+`total-requests` job:
+
+[source,js]
+--------------------------------------------------
+PUT _xpack/ml/calendars/planned-outages/jobs/total-requests
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:calendar_outages_openjob]
+
+The API returns the following results:
+
+[source,js]
+----
+{
+  "calendar_id": "planned-outages",
+  "job_ids": [
+    "total-requests"
+  ]
+}
+----
+//TESTRESPONSE

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

@@ -11,7 +11,10 @@ This API enables you to instantiate a calendar.
 
 `PUT _xpack/ml/calendars/<calendar_id>`
 
-//===== Description
+===== Description
+
+For more information, see
+{xpack-ref}/ml-calendars.html[Calendars and Scheduled Events].
 
 ==== Path Parameters
 
@@ -24,6 +27,7 @@ This API enables you to instantiate a calendar.
 `description`::
   (string) A description of the calendar.
 
+
 ==== Authorization
 
 You must have `manage_ml`, or `manage` cluster privileges to use this API.
@@ -31,5 +35,22 @@ 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
+==== Examples
+
+The following example creates the `planned-outages` calendar:
+
+[source,js]
+--------------------------------------------------
+PUT _xpack/ml/calendars/planned-outages
+--------------------------------------------------
+// CONSOLE
+
+When the calendar is created, you receive the following results:
+[source,js]
+----
+{
+  "calendar_id": "planned-outages",
+  "job_ids": []
+}
+----
+//TESTRESPONSE