[DOCS] Formatted roles API (elastic/x-pack-elasticsearch#2577)
* [DOCS] Formatted roles API
* [DOCS] Addressed feedback about roles API
Original commit: elastic/x-pack-elasticsearch@413fc33954d0268c65bd6d5f0fa3548cc4806762
=== Role Management APIs
The Roles API enables you to add, remove, and retrieve roles in the `native`
-realm. To use this API, you must have at least the `manage_security` cluster
+realm.
+
+==== Request
+
+`GET /_xpack/security/role` +
+
+`GET /_xpack/security/role/<name>` +
+
+`POST /_xpack/security/role/<name>/_clear_cache` +
+
+`POST /_xpack/security/role/<name>` +
+
+`PUT /_xpack/security/role/<name>`
+
+
+==== Description
+
+The Roles API is generally the preferred way to manage roles, rather than using
+file-based role management. For more information, see
+{xpack-ref}/authorization.html[Configuring Role-based Access Control].
+
+
+==== Path Parameters
+
+`name`::
+ (string) The name of the role. If you do not specify this parameter, the
+ Get Roles API returns information about all roles.
+
+
+==== Request Body
+
+The following parameters can be specified in the body of a PUT or POST request
+and pertain to adding a role:
+
+`cluster`:: (list) A list of cluster privileges. These privileges define the
+cluster level actions that users with this role are able to execute.
+
+`indices`:: (list) A list of indices permissions entries.
+`field_security`::: (list) The document fields that the owners of the role have
+read access to. For more information, see
+{xpack-ref}/field-and-document-access-control.html[Setting Up Field and Document Level Security].
+`names` (required)::: (list) A list of indices (or index name patterns) to which the
+permissions in this entry apply.
+`privileges`(required)::: (list) The index level privileges that the owners of the role
+have on the specified indices.
+`query`::: A search query that defines the documents the owners of the role have
+read access to. A document within the specified indices must match this query in
+order for it to be accessible by the owners of the role.
+
+`metadata`:: (object) Optional meta-data. Within the `metadata` object, keys
+that begin with `_` are reserved for system usage.
+
+`run_as`:: (list) A list of users that the owners of this role can impersonate.
+For more information, see
+{xpack-ref}/run-as-privilege.html[Submitting Requests on Behalf of Other Users].
+
+For more information, see {xpack-ref}/defining-roles.html[Defining Roles].
+
+
+==== Authorization
+
+To use this API, you must have at least the `manage_security` cluster
privilege.
-NOTE: The Roles API is now the preferred way to manage roles.
+
+==== Examples
[[security-api-put-role]]
To add a role, submit a PUT or POST request to the `/_xpack/security/role/<rolename>`
@@ -35,15 +97,6 @@ POST /_xpack/security/role/my_admin_role
--------------------------------------------------
// CONSOLE
-The `name`, `cluster`, and `indices` fields are required at the top-level.
-Within the `indices` array, the `names` and `privileges` fields are required.
-Within the `metadata` object, keys beginning with `_` are reserved for system
-usage.
-
-The `field_security` and `query` fields are both optional. They are used to
-implement field and document level security. For more information, see
-{xpack-ref}/field-and-document-access-control.html[Setting Up Field and Document Level Security].
-
A successful call returns a JSON structure that shows whether the role has been
created or updated.
