From b55ab98914df080b39570ecf52e69f035ba80f55 Mon Sep 17 00:00:00 2001
From: Lisa Cawley <lcawley@elastic.co>
Date: Fri, 22 Sep 2017 10:40:20 -0700
Subject: [PATCH] [DOCS] Formatted role mapping API
 (elastic/x-pack-elasticsearch#2576)

* [DOCS] Formatted role mapping API

* [DOCS] Addressed feedback in role mapping API

Original commit: elastic/x-pack-elasticsearch@baba26c8ede64585069194be52c4370f8f58fc4e
---
 .../rest-api/security/role-mapping.asciidoc   | 74 ++++++++++++++++---
 1 file changed, 62 insertions(+), 12 deletions(-)

diff --git a/docs/en/rest-api/security/role-mapping.asciidoc b/docs/en/rest-api/security/role-mapping.asciidoc
index 81ac7e4f1e4..d3dcb94e259 100644
--- a/docs/en/rest-api/security/role-mapping.asciidoc
+++ b/docs/en/rest-api/security/role-mapping.asciidoc
@@ -2,15 +2,69 @@
 [[security-api-role-mapping]]
 === Role Mapping APIs
 
-The Role Mapping API enables you to add, remove, and retrieve role-mappings.
-To use this API, you must have at least the `manage_security` cluster privilege.
+The Role Mapping API enables you to add, remove, and retrieve role mappings.
 
-NOTE: The API requires that each role-mapping have a distinct name. The name is
+==== Request
+
+`GET /_xpack/security/role_mapping` +
+
+`GET /_xpack/security/role_mapping/<name>` +
+
+`DELETE /_xpack/security/role_mapping/<name>` +
+
+`POST /_xpack/security/role_mapping/<name>` +
+
+`PUT /_xpack/security/role_mapping/<name>`
+
+==== Description
+
+NOTE: The API requires that each role mapping have a distinct name. The name is
  used solely as an identifier to facilitate interaction via the API, and does
  not affect the behavior of the mapping in any way.
 
+For more information, see
+{xpack-ref}/mapping-roles.html[Mapping Users and Groups to Roles].
+
+==== Path Parameters
+
+`name`::
+ (string) The distinct name that identifies the role mapping. If you do not
+ specify this parameter, the Get Role Mappings API returns information about all
+ role mappings.
+
+
+==== Request Body
+
+The following parameters can be specified in the body of a PUT or POST request
+and pertain to adding a role mapping:
+
+`enabled` (required)::
+(boolean)  Mappings that have `enabled` set to `false` are ignored when role
+mapping is performed.
+
+`metadata`::
+(object) Additional metadata that helps define which roles are assigned to each
+user. Within the `metadata` object, keys beginning with `_` are reserved for
+system usage.
+
+`roles` (required)::
+(list) A list of roles that are granted to the users that match the role-mapping
+rules.
+
+`rules` (required)::
+(object) The rules that determine which users should be matched by the mapping.
+A rule is a logical condition that is expressed by using a JSON DSL.
+
+
+==== Authorization
+
+To use this API, you must have at least the `manage_security` cluster privilege.
+
+
+==== Examples
+
 [[security-api-put-role-mapping]]
-To add a role-mapping, submit a PUT or POST request to the `/_xpack/security/role_mapping/<name>`
+To add a role mapping, submit a PUT or POST request to the `/_xpack/security/role_mapping/<name>`
 endpoint:
 
 [source,js]
@@ -28,14 +82,10 @@ POST /_xpack/security/role_mapping/administrators
 }
 --------------------------------------------------
 // CONSOLE
-<1> Mappings that have `enabled` set to `false` will be ignored when role-mapping
+<1> Mappings that have `enabled` set to `false` will be ignored when role mapping
     is performed.
 <2> Metadata is optional
 
-The `roles`, `enabled`, and `rules` fields are required at the top-level.
-Within the `metadata` object, keys beginning with `_` are reserved for system
-usage.
-
 A successful call returns a JSON structure that shows whether the mapping has
 been created or updated.
 
@@ -51,7 +101,7 @@ been created or updated.
 <1> When an existing mapping is updated, `created` is set to false.
 
 [[security-api-get-role-mapping]]
-To retrieve a role-mapping, issue a GET request to the
+To retrieve a role mapping, issue a GET request to the
 `/_xpack/security/role_mapping/<name>` endpoint:
 
 [source,js]
@@ -61,7 +111,7 @@ GET /_xpack/security/role_mapping/administrators
 // CONSOLE
 // TEST[continued]
 
-A successful call an object, where the keys are the
+A successful call retrieves an object, where the keys are the
 names of the request mappings, and the values are
 the JSON representation of those mappings.
 If there is no mapping with the requested name, the
@@ -107,7 +157,7 @@ GET /_xpack/security/role_mapping
 // TEST[continued]
 
 [[security-api-delete-role-mapping]]
-To delete a role-mapping, submit a DELETE request to the
+To delete a role mapping, submit a DELETE request to the
 `/_xpack/security/role_mapping/<name>` endpoint:
 
 [source,js]