[DOCS] Enable testing for API key examples (#39583)

elastic · Mar 19, 2019 · 724de43 · 724de43
1 parent d2c957e
commit 724de43
Show file tree

Hide file tree

Showing 3 changed files with 128 additions and 53 deletions.
diff --git a/x-pack/docs/en/rest-api/security/create-api-keys.asciidoc b/x-pack/docs/en/rest-api/security/create-api-keys.asciidoc
@@ -1,6 +1,6 @@
 [role="xpack"]
 [[security-api-create-api-key]]
-=== Create API Key API
+=== Create API key API
 ++++
 <titleabbrev>Create API keys</titleabbrev>
 ++++
@@ -20,14 +20,15 @@ you can explicitly enable the `xpack.security.authc.api_key.enabled` setting. Wh
 you are running in production mode, a bootstrap check prevents you from enabling 
 the API key service unless you also enable TLS on the HTTP interface. 
 
-A successful create API key API call returns a JSON structure that contains 
-the unique id, the name to identify API key, the API key and the expiration if 
-applicable for the API key in milliseconds. 
+A successful create API key API call returns a JSON structure that contains the
+API key, its unique id, and its name. If applicable, it also returns expiration
+information for the API key in milliseconds. 
 
-NOTE: By default API keys never expire. You can specify expiration at the time of 
-creation for the API keys. 
+NOTE: By default, API keys never expire. You can specify expiration information
+when you create the API keys. 
 
-See <<api-key-service-settings>> for configuration settings related to API key service.
+See <<api-key-service-settings>> for configuration settings related to API key
+service.
 
 ==== Request Body
 
@@ -36,15 +37,16 @@ The following parameters can be specified in the body of a POST or PUT request:
 `name`::
 (string) Specifies the name for this API key.
 
-`role_descriptors`::
-(array-of-role-descriptor) Optional array of role descriptor for this API key. The role descriptor 
-must be a subset of permissions of the authenticated user. The structure of role 
-descriptor is same as the request for create role API. For more details on role 
-see <<security-api-roles, Role Management APIs>>.
-If the role descriptors are not provided then permissions of the authenticated user are applied.
+`role_descriptors` (required)::
+(array-of-role-descriptor) An array of role descriptors for this API key. This
+parameter is required but can be an empty array, which applies the permissions
+of the authenticated user. If you supply role descriptors, they must be a subset
+of the authenticated user's permissions. The structure of role descriptor is the
+same as the request for create role API. For more details, see
+<<security-api-roles,role management APIs>>.
 
 `expiration`::
-(string) Optional expiration time for the API key. By default API keys never expire.
+(string) Optional expiration time for the API key. By default, API keys never expire.
 
 ==== Examples
 

diff --git a/x-pack/docs/en/rest-api/security/get-api-keys.asciidoc b/x-pack/docs/en/rest-api/security/get-api-keys.asciidoc
@@ -1,6 +1,6 @@
 [role="xpack"]
 [[security-api-get-api-key]]
-=== Get API Key information API
+=== Get API key information API
 ++++
 <titleabbrev>Get API key information</titleabbrev>
 ++++
@@ -22,54 +22,88 @@ The following parameters can be specified in the query parameters of a GET reque
 pertain to retrieving api keys:
 
 `id` (optional)::
-(string) An API key id. This parameter cannot be used with any of `name`, `realm_name` or
-         `username` are used.
+(string) An API key id. This parameter cannot be used with any of `name`,
+`realm_name` or `username` are used.
 
 `name` (optional)::
-(string) An API key name. This parameter cannot be used with any of `id`, `realm_name` or
-                          `username` are used.
+(string) An API key name. This parameter cannot be used with any of `id`,
+`realm_name` or `username` are used.
 
 `realm_name` (optional)::
-(string) The name of an authentication realm. This parameter cannot be used with either `id` or `name`.
+(string) The name of an authentication realm. This parameter cannot be used with
+either `id` or `name`.
 
 `username` (optional)::
-(string) The username of a user. This parameter cannot be used with either `id` or `name`.
+(string) The username of a user. This parameter cannot be used with either `id`
+or `name`.
 
 NOTE: While all parameters are optional, at least one of them is required.
 
 ==== Examples
 
-The following example to retrieve the API key identified by specified `id`:
+If you create an API key as follows:
+
+[source, js]
+------------------------------------------------------------
+POST /_security/api_key
+{
+  "name": "my-api-key",
+  "role_descriptors": {}
+}
+------------------------------------------------------------
+// CONSOLE
+// TEST
+
+A successful call returns a JSON structure that provides
+API key information. For example:
 
 [source,js]
 --------------------------------------------------
-GET /_security/api_key?id=dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==
+{
+  "id":"VuaCfGcBCdbkQm-e5aOx",
+  "name":"my-api-key",
+  "api_key":"ui2lp2axTNmsyakw9tvNnw"
+}
 --------------------------------------------------
-// NOTCONSOLE
+// TESTRESPONSE[s/VuaCfGcBCdbkQm-e5aOx/$body.id/]
+// TESTRESPONSE[s/ui2lp2axTNmsyakw9tvNnw/$body.api_key/]
 
-whereas the following example to retrieve the API key identified by specified `name`:
+You can use the following example to retrieve the API key by ID:
 
 [source,js]
 --------------------------------------------------
-GET /_security/api_key?name=hadoop_myuser_key
+GET /_security/api_key?id=VuaCfGcBCdbkQm-e5aOx
 --------------------------------------------------
-// NOTCONSOLE
+// CONSOLE
+// TEST[s/VuaCfGcBCdbkQm-e5aOx/$body.id/]
+// TEST[continued]
+
+You can use the following example to retrieve the API key by name:
+
+[source,js]
+--------------------------------------------------
+GET /_security/api_key?name=my-api-key
+--------------------------------------------------
+// CONSOLE
+// TEST[continued]
 
 The following example retrieves all API keys for the `native1` realm:
 
 [source,js]
 --------------------------------------------------
 GET /_security/api_key?realm_name=native1
 --------------------------------------------------
-// NOTCONSOLE
+// CONSOLE
+// TEST[continued]
 
 The following example retrieves all API keys for the user `myuser` in all realms:
 
 [source,js]
 --------------------------------------------------
 GET /_security/api_key?username=myuser
 --------------------------------------------------
-// NOTCONSOLE
+// CONSOLE
+// TEST[continued]
 
 Finally, the following example retrieves all API keys for the user `myuser` in
  the `native1` realm immediately:
@@ -78,7 +112,8 @@ Finally, the following example retrieves all API keys for the user `myuser` in
 --------------------------------------------------
 GET /_security/api_key?username=myuser&realm_name=native1
 --------------------------------------------------
-// NOTCONSOLE
+// CONSOLE
+// TEST[continued]
 
 A successful call returns a JSON structure that contains the information of one or more API keys that were retrieved.
 
@@ -112,7 +147,8 @@ A successful call returns a JSON structure that contains the information of one
 <2> Id for the API key
 <3> Name of the API key
 <4> Creation time for the API key in milliseconds
-<5> optional expiration time for the API key in milliseconds
-<6> invalidation status for the API key, `true` if the key has been invalidated else `false`
-<7> principal for which this API key was created
-<8> realm name of the principal for which this API key was created
+<5> Optional expiration time for the API key in milliseconds
+<6> Invalidation status for the API key. If the key has been invalidated, it has
+a value of `true`. Otherwise, it is `false`.
+<7> Principal for which this API key was created
+<8> Realm name of the principal for which this API key was created
diff --git a/x-pack/docs/en/rest-api/security/invalidate-api-keys.asciidoc b/x-pack/docs/en/rest-api/security/invalidate-api-keys.asciidoc
@@ -1,6 +1,6 @@
 [role="xpack"]
 [[security-api-invalidate-api-key]]
-=== Invalidate API Key API
+=== Invalidate API key API
 ++++
 <titleabbrev>Invalidate API key</titleabbrev>
 ++++
@@ -13,55 +13,88 @@ Invalidates one or more API keys.
 
 ==== Description
 
-The API keys created by <<security-api-create-api-key,create API Key>> can be invalidated
-using this API.
+The API keys created by <<security-api-create-api-key,create API Key>> can be
+invalidated using this API.
 
 ==== Request Body
 
 The following parameters can be specified in the body of a DELETE request and
 pertain to invalidating api keys:
 
 `id` (optional)::
-(string) An API key id. This parameter cannot be used with any of `name`, `realm_name` or
-         `username` are used.
+(string) An API key id. This parameter cannot be used with any of `name`,
+`realm_name` or `username` are used.
 
 `name` (optional)::
-(string) An API key name. This parameter cannot be used with any of `id`, `realm_name` or
-                          `username` are used.
+(string) An API key name. This parameter cannot be used with any of `id`,
+`realm_name` or `username` are used.
 
 `realm_name` (optional)::
-(string) The name of an authentication realm. This parameter cannot be used with either `api_key_id` or `api_key_name`.
+(string) The name of an authentication realm. This parameter cannot be used with
+either `api_key_id` or `api_key_name`.
 
 `username` (optional)::
-(string) The username of a user. This parameter cannot be used with either `api_key_id` or `api_key_name`.
+(string) The username of a user. This parameter cannot be used with either
+`api_key_id` or `api_key_name`.
 
 NOTE: While all parameters are optional, at least one of them is required.
 
 ==== Examples
 
+If you create an API key as follows:
+
+[source, js]
+------------------------------------------------------------
+POST /_security/api_key
+{
+  "name": "my-api-key",
+  "role_descriptors": {}
+}
+------------------------------------------------------------
+// CONSOLE
+// TEST
+
+A successful call returns a JSON structure that provides
+API key information. For example:
+
+[source,js]
+--------------------------------------------------
+{
+  "id":"VuaCfGcBCdbkQm-e5aOx",
+  "name":"my-api-key",
+  "api_key":"ui2lp2axTNmsyakw9tvNnw"
+}
+--------------------------------------------------
+// TESTRESPONSE[s/VuaCfGcBCdbkQm-e5aOx/$body.id/]
+// TESTRESPONSE[s/ui2lp2axTNmsyakw9tvNnw/$body.api_key/]
+
 The following example invalidates the API key identified by specified `id` immediately:
 
 [source,js]
 --------------------------------------------------
 DELETE /_security/api_key
 {
-  "id" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ=="
+  "id" : "VuaCfGcBCdbkQm-e5aOx"
 }
 --------------------------------------------------
-// NOTCONSOLE
+// CONSOLE
+// TEST[s/VuaCfGcBCdbkQm-e5aOx/$body.id/]
+// TEST[continued]
 
-whereas the following example invalidates the API key identified by specified `name` immediately:
+The following example invalidates the API key identified by specified `name` immediately:
 
 [source,js]
 --------------------------------------------------
 DELETE /_security/api_key
 {
-  "name" : "hadoop_myuser_key"
+  "name" : "my-api-key"
 }
 --------------------------------------------------
-// NOTCONSOLE
+// CONSOLE
+// TEST
 
-The following example invalidates all API keys for the `native1` realm immediately:
+The following example invalidates all API keys for the `native1` realm
+immediately:
 
 [source,js]
 --------------------------------------------------
@@ -70,9 +103,11 @@ DELETE /_security/api_key
   "realm_name" : "native1"
 }
 --------------------------------------------------
-// NOTCONSOLE
+// CONSOLE
+// TEST
 
-The following example invalidates all API keys for the user `myuser` in all realms immediately:
+The following example invalidates all API keys for the user `myuser` in all
+realms immediately:
 
 [source,js]
 --------------------------------------------------
@@ -81,7 +116,8 @@ DELETE /_security/api_key
   "username" : "myuser"
 }
 --------------------------------------------------
-// NOTCONSOLE
+// CONSOLE
+// TEST
 
 Finally, the following example invalidates all API keys for the user `myuser` in
  the `native1` realm immediately:
@@ -94,7 +130,8 @@ DELETE /_security/api_key
   "realm_name" : "native1"
 }
 --------------------------------------------------
-// NOTCONSOLE
+// CONSOLE
+// TEST
 
 A successful call returns a JSON structure that contains the ids of the API keys that were invalidated, the ids
 of the API keys that had already been invalidated, and potentially a list of errors encountered while invalidating