[DOCS] Added licensing APIs (elastic/x-pack-elasticsearch#4026)

Original commit: elastic/x-pack-elasticsearch@0e50cc0d64

docs/build.gradle

@@ -61,6 +61,9 @@ buildRestTests.expectedUnconvertedCandidates = [
         'en/watcher/trigger/schedule/weekly.asciidoc',
         'en/watcher/trigger/schedule/yearly.asciidoc',
         'en/watcher/troubleshooting.asciidoc',
+        'en/rest-api/license/delete-license.asciidoc',
+        'en/rest-api/license/start-trial.asciidoc',
+        'en/rest-api/license/update-license.asciidoc',
         'en/ml/api-quickref.asciidoc',
         'en/rest-api/ml/delete-calendar-event.asciidoc',
         'en/rest-api/ml/delete-snapshot.asciidoc',

docs/en/rest-api/index.asciidoc

@@ -9,6 +9,7 @@ directly to configure and access {xpack} features.
 
 * <<info-api, Info API>>
 * <<graph-explore-api, Graph Explore API>>
+* <<licensing-apis>>
 * <<ml-apis, Machine Learning APIs>>
 * <<security-api,Security APIs>>
 * <<watcher-api, Watcher APIs>>
@@ -19,9 +20,10 @@ directly to configure and access {xpack} features.
 
 include::info.asciidoc[]
 include::graph/explore.asciidoc[]
+include::licensing.asciidoc[]
+include::migration.asciidoc[]
 include::ml-api.asciidoc[]
+include::rollup-api.asciidoc[]
 include::security.asciidoc[]
 include::watcher.asciidoc[]
-include::rollup-api.asciidoc[]
-include::migration.asciidoc[]
 include::defs.asciidoc[]

docs/en/rest-api/license/delete-license.asciidoc

@@ -0,0 +1,43 @@
+[role="xpack"]
+[[delete-license]]
+=== Delete License API
+
+This API enables you to delete licensing information.
+
+[float]
+==== Request
+
+`DELETE /_xpack/license`
+
+[float]
+==== Description
+
+When your license expires, {xpack} operates in a degraded mode.  For more
+information, see {xpack-ref}/license-expiration.html[License Expiration].
+
+[float]
+==== Authorization
+
+You must have `manage` cluster privileges to use this API.
+For more information, see
+{xpack-ref}/security-privileges.html[Security Privileges].
+
+[float]
+==== Examples
+
+The following example queries the info API:
+
+[source,js]
+------------------------------------------------------------
+DELETE _xpack/license
+------------------------------------------------------------
+// CONSOLE
+// TEST[skip:license testing issues]
+
+When the license is successfully deleted, the API returns the following response:
+[source,js]
+------------------------------------------------------------
+{
+  "acknowledged": true
+}
+------------------------------------------------------------

docs/en/rest-api/license/get-license.asciidoc

@@ -0,0 +1,75 @@
+[role="xpack"]
+[[get-license]]
+=== Get License API
+
+This API enables you to retrieve licensing information.
+
+[float]
+==== Request
+
+`GET /_xpack/license`
+
+[float]
+==== Description
+
+This API returns information about the type of license, when it was issued, and
+when it expires, for example.
+
+For more information about the different types of licenses, see
+https://www.elastic.co/subscriptions.
+
+
+[float]
+==== Query Parameters
+
+`local`::
+  (boolean) Specifies whether to retrieve local information. The default value
+  is `false`, which means the information is retrieved from the master node.
+
+
+[float]
+==== Authorization
+
+You must have `monitor` cluster privileges to use this API.
+For more information, see
+{xpack-ref}/security-privileges.html[Security Privileges].
+
+
+[float]
+==== Examples
+
+The following example provides information about a basic license:
+
+[source,js]
+--------------------------------------------------
+GET _xpack/license
+--------------------------------------------------
+// CONSOLE
+
+[source,js]
+--------------------------------------------------
+{
+  "license" : {
+    "status" : "active",
+    "uid" : "cbff45e7-c553-41f7-ae4f-9205eabd80xx",
+    "type" : "trial",
+    "issue_date" : "2018-02-22T23:12:05.550Z",
+    "issue_date_in_millis" : 1519341125550,
+    "expiry_date" : "2018-03-24T23:12:05.550Z",
+    "expiry_date_in_millis" : 1521933125550,
+    "max_nodes" : 1000,
+    "issued_to" : "test",
+    "issuer" : "elasticsearch",
+    "start_date_in_millis" : -1
+  }
+}
+--------------------------------------------------
+// TESTRESPONSE[s/"cbff45e7-c553-41f7-ae4f-9205eabd80xx"/$body.license.uid/]
+// TESTRESPONSE[s/"trial"/$body.license.type/]
+// TESTRESPONSE[s/"2018-02-22T23:12:05.550Z"/$body.license.issue_date/]
+// TESTRESPONSE[s/1519341125550/$body.license.issue_date_in_millis/]
+// TESTRESPONSE[s/"2018-03-24T23:12:05.550Z"/$body.license.expiry_date/]
+// TESTRESPONSE[s/1521933125550/$body.license.expiry_date_in_millis/]
+// TESTRESPONSE[s/1000/$body.license.max_nodes/]
+// TESTRESPONSE[s/"test"/$body.license.issued_to/]
+// TESTRESPONSE[s/"elasticsearch"/$body.license.issuer/]

docs/en/rest-api/license/get-trial-status.asciidoc

@@ -0,0 +1,52 @@
+[role="xpack"]
+[[get-trial-status]]
+=== Get Trial Status API
+
+This API enables you to check the status of your trial license.
+
+[float]
+==== Request
+
+`GET _xpack/license/trial_status`
+
+[float]
+==== Description
+
+If a license is not already registered for the cluster, one is generated when
+the nodes start. By default, this is a 30-day trial license that gives access
+to all {xpack} features.
+
+NOTE: You are allowed to initiate a trial license only if your cluster has not
+already activated a trial license for the current major X-Pack version. For
+example, if you have already activated a trial for v6.0, you cannot start a new
+trial until v7.0. You can, however, contact `info@elastic.co` to request an
+extended trial license.
+
+For more information about the different types of licenses, see
+https://www.elastic.co/subscriptions.
+
+==== Authorization
+
+You must have `monitor` cluster privileges to use this API.
+For more information, see
+{xpack-ref}/security-privileges.html[Security Privileges].
+
+[float]
+==== Examples
+
+The following example checks whether you are eligible to start a trial:
+
+[source,js]
+------------------------------------------------------------
+GET _xpack/license/trial_status
+------------------------------------------------------------
+// CONSOLE
+
+Example response:
+[source,js]
+------------------------------------------------------------
+{
+  "eligible_to_start_trial": true
+}
+------------------------------------------------------------
+// TESTRESPONSE[s/"eligible_to_start_trial": true/"eligible_to_start_trial": $body.eligible_to_start_trial/]

docs/en/rest-api/license/start-trial.asciidoc

@@ -0,0 +1,54 @@
+[role="xpack"]
+[[start-trial]]
+=== Start Trial API
+
+This API starts a 30-day trial license.
+
+[float]
+==== Request
+
+`POST _xpack/license/start_trial`
+
+[float]
+==== Description
+
+The `start trial` API enables you to upgrade from a basic license to a 30-day
+trial license, which gives access to all {xpack} features.
+
+NOTE: You are allowed to initiate a trial license only if your cluster has not
+already activated a trial license for the current major X-Pack version. For
+example, if you have already activated a trial for v6.0, you cannot start a new
+trial until v7.0. You can, however, contact `info@elastic.co` to request an
+extended trial license.
+
+To check the status of your trial license, use the following API:
+<<get-trial-status>>. 
+
+For more information about the different types of licenses, see
+https://www.elastic.co/subscriptions.
+
+==== Authorization
+
+You must have `manage` cluster privileges to use this API.
+For more information, see
+{xpack-ref}/security-privileges.html[Security Privileges].
+
+[float]
+==== Examples
+
+The following example checks whether you are eligible to start a trial:
+
+[source,js]
+------------------------------------------------------------
+POST _xpack/license/start_trial
+------------------------------------------------------------
+// CONSOLE
+// TEST[skip:license testing issues]
+
+Example response:
+[source,js]
+------------------------------------------------------------
+{
+  "trial_was_started": true
+}
+------------------------------------------------------------

docs/en/rest-api/license/update-license.asciidoc

@@ -0,0 +1,160 @@
+[role="xpack"]
+[[update-license]]
+=== Update License API
+
+This API enables you to update your license.
+
+[float]
+==== Request
+
+`PUT _xpack/license`
+
+[float]
+==== Description
+
+You can update your license at runtime without shutting down your nodes.
+License updates take effect immediately.  If the license you are installing does
+not support all of the features that were available with your previous license,
+however, you are notified in the response.  You must then re-submit the API
+request with the `acknowledge` parameter set to `true`.
+
+For more information about the different types of licenses, see
+https://www.elastic.co/subscriptions.
+
+[float]
+==== Query Parameters
+
+`acknowledge`::
+  (boolean) Specifies whether you acknowledge the license changes. The default
+  value is `false`.
+
+[float]
+==== Request Body
+
+`licenses`::
+  (array) A sequence of one or more JSON documents containing the license
+  information.
+
+
+[float]
+==== Authorization
+
+If {security} is enabled, you need `manage` cluster privileges to install the
+license.
+
+If {security} is enabled and you are installing a gold or platinum license, you
+must enable TLS on the transport networking layer before you install the license.
+See <<configuring-tls>>.
+
+[float]
+==== Examples
+
+The following example updates to a basic license:
+
+[source,js]
+------------------------------------------------------------
+POST _xpack/license
+{
+  "licenses": [
+    {
+      "uid":"893361dc-9749-4997-93cb-802e3d7fa4xx",
+      "type":"basic",
+      "issue_date_in_millis":1411948800000,
+      "expiry_date_in_millis":1914278399999,
+      "max_nodes":1,
+      "issued_to":"issuedTo",
+      "issuer":"issuer",
+      "signature":"xx"
+    }
+    ]
+}
+------------------------------------------------------------
+// CONSOLE
+// TEST[skip:license testing issues]
+
+NOTE: These values are invalid; you must substitute the appropriate content
+from your license file.
+
+You can alternatively use a `curl` command, for example:
+
+[source,js]
+[source,shell]
+------------------------------------------------------------
+curl -XPUT -u <user> 'http://<host>:<port>/_xpack/license' -H "Content-Type: application/json" -d @license.json
+------------------------------------------------------------
+// NOTCONSOLE
+
+On Windows machine, use the following command:
+
+[source,shell]
+------------------------------------------------------------
+gc .\license.json |  Invoke-WebRequest -uri http://<host>:<port>/_xpack/license -Credential elastic -Method Put -ContentType "application/json"
+------------------------------------------------------------
+
+In these examples,
+
+* `<user>` is a user ID with the appropriate authority.
+* `<host>` is the hostname of the {es} node (`localhost` if executing
+  locally)
+* `<port>` is the http port (defaults to `9200`)
+* `license.json` is the license JSON file
+
+NOTE:  If your {es} node has SSL enabled on the HTTP interface, you must
+  start your URL with `https://`
+
+If you previously had a license with more features than the basic license, you
+receive the following response:
+
+[source,js]
+------------------------------------------------------------
+  {
+  "acknowledged": false,
+  "license_status": "valid",
+  "acknowledge": {
+    "message": """This license update requires acknowledgement. To acknowledge the license, please read the following messages and update the license again, this time with the "acknowledge=true" parameter:""",
+    "watcher": [
+      "Watcher will be disabled"
+    ],
+    "logstash": [
+      "Logstash will no longer poll for centrally-managed pipelines"
+    ],
+    "security": [
+      "The following X-Pack security functionality will be disabled: ..." ]
+    }
+}
+------------------------------------------------------------
+
+To complete the update, you must re-submit the API request and set the
+`acknowledge` parameter to `true`. For example:
+
+[source,js]
+------------------------------------------------------------
+POST _xpack/license?acknowledge=true
+{
+  "licenses": [
+    {
+      "uid":"893361dc-9749-4997-93cb-802e3d7fa4xx",
+      "type":"basic",
+      "issue_date_in_millis":1411948800000,
+      "expiry_date_in_millis":1914278399999,
+      "max_nodes":1,
+      "issued_to":"issuedTo",
+      "issuer":"issuer",
+      "signature":"xx"
+    }
+    ]
+}
+------------------------------------------------------------
+// CONSOLE
+// TEST[skip:license testing issues]
+
+Alternatively:
+
+[source,sh]
+------------------------------------------------------------
+curl -XPUT -u elastic 'http://<host>:<port>/_xpack/license?acknowledge=true' -H "Content-Type: application/json" -d @license.json
+------------------------------------------------------------
+// NOTCONSOLE
+
+For more information about the features that are disabled when you downgrade
+your license, see {xpack-ref}/license-expiration.html[License Expiration].

docs/en/rest-api/licensing.asciidoc

@@ -0,0 +1,18 @@
+[role="xpack"]
+[[licensing-apis]]
+== Licensing APIs
+
+You can use the following APIs to manage your licenses:
+
+* <<delete-license>>
+* <<get-license>>
+* <<get-trial-status>>
+* <<start-trial>>
+* <<update-license>>
+
+
+include::license/delete-license.asciidoc[]
+include::license/get-license.asciidoc[]
+include::license/get-trial-status.asciidoc[]
+include::license/start-trial.asciidoc[]
+include::license/update-license.asciidoc[]

docs/en/rest-api/migration/deprecation.asciidoc

@@ -1,13 +1,13 @@
 [role="xpack"]
 [[migration-api-deprecation]]
-== Deprecation Info APIs
+=== Deprecation Info APIs
 
 The deprecation API is to be used to retrieve information about different
 cluster, node, and index level settings that use deprecated features that will
 be removed or changed in the next major version.
 
 [float]
-=== Request
+==== Request
 
 `GET /_xpack/migration/deprecations` +
 
@@ -16,7 +16,7 @@ be removed or changed in the next major version.
 //=== Description
 
 [float]
-=== Path Parameters
+==== Path Parameters
 
 `index_name`::
   (string) Identifier for the index. It can be an index name or a wildcard
@@ -28,7 +28,7 @@ be removed or changed in the next major version.
 //=== Authorization
 
 [float]
-=== Examples
+==== Examples
 
 To see the list of offenders in your cluster, submit a GET request to the
 `_xpack/migration/deprecations` endpoint: