[DOCS] Format the clear cache API (elastic/x-pack-elasticsearch#2574)
* [DOCS] Format the clear cache API
* [DOCS] Fixed formatting in clear cache API
Original commit: elastic/x-pack-elasticsearch@f3218ce138b97023acb032222a10e6c635957672
The Clear Cache API evicts users from the user cache. You can completely clear
the cache or evict specific users.
+==== Request
+
+`POST _xpack/security/realm/<realms>/_clear_cache` +
+
+`POST _xpack/security/realm/<realms>/_clear_cache?usernames=<usernames>`
+
+
+==== Description
+
+User credentials are cached in memory on each node to avoid connecting to a
+remote authentication service or hitting the disk for every incoming request.
+There are realm settings that you can use to configure the user cache. For more
+information, see {xpack-ref}/controlling-user-cache.html[Controlling the User Cache].
+
+==== Path Parameters
+
+`realms` (required)::
+ (list) A comma-separated list of the realms to clear.
+
+`usernames`::
+ (list) A comma-separated list of the users to clear from the cache. If you
+ do not specify this parameter, the API evicts all users from the user cache.
+
+==== Examples
+
For example, to evict all users cached by the `file` realm:
[source,js]
@@ -29,6 +54,3 @@ list:
POST _xpack/security/realm/default_file,ldap1/_clear_cache
------------------------------------------------------------
// CONSOLE
-
-For more information, see
-{xpack-ref}/controlling-user-cache.html[Controlling the User Cache].
