[id='rest_v2_create_cache']
= Creating Caches
Create named caches across {brandname} clusters with `POST` requests that
include XML or JSON configuration in the payload.

[source,options="nowrap",subs=attributes+]
----
POST /rest/v2/caches/{cacheName}
----

.Headers

|===
|Header |Required or Optional |Parameter

|`Content-Type`
|REQUIRED
|Sets the https://en.wikipedia.org/wiki/Media_type[MediaType] for the
{brandname} configuration payload; either `application/xml` or
`application/json`.
| `Flags` | OPTIONAL | Used to set https://docs.jboss.org/infinispan/10.0/apidocs/org/infinispan/commons/api/CacheContainerAdmin.AdminFlag.html[AdminFlags]
|===

include::ref_infinispan_caches.adoc[leveloffset=+1]

[id='rest_v2_modify_cache']
= Modifying Caches
Make changes to attributes in cache configurations across {brandname} clusters with `PUT` requests that include XML or JSON configuration in the payload.

[NOTE]
====
You can modify a cache only if the changes are compatible with the existing configuration.

For example you cannot use a replicated cache configuration to modify a distributed cache.
Likewise if you create a cache configuration with a specific attribute, you cannot modify the configuration to use a different attribute instead.
For example, attempting to modify cache configuration by specifying a value for the `max-count` attribute results in invalid configuration if the `max-size` is already set.
====

[source,options="nowrap",subs=attributes+]
----
PUT /rest/v2/caches/{cacheName}
----

.Headers

|===
|Header |Required or Optional |Parameter

|`Content-Type`
|REQUIRED
|Sets the https://en.wikipedia.org/wiki/Media_type[MediaType] for the
{brandname} configuration payload; either `application/xml` or
`application/json`.
| `Flags` | OPTIONAL | Used to set link:{javadocroot}/org/infinispan/commons/api/CacheContainerAdmin.AdminFlag.html[AdminFlags]
|===

[id='rest_v2_cache_exists']
= Verifying Caches
Check if a cache exists in {brandname} clusters with `HEAD` requests.

[source,options="nowrap",subs=attributes+]
----
HEAD /rest/v2/caches/{cacheName}
----

Retrieve a caches health with `GET` requests.

[source,options="nowrap",subs=attributes+]
----
GET /rest/v2/caches/{cacheName}?action=health
----

[id='rest_v2_create_cache_template']
= Creating Caches with Templates
Create caches from {brandname} templates with `POST` requests and the
`?template=` parameter.

[source,options="nowrap",subs=attributes+]
----
POST /rest/v2/caches/{cacheName}?template={templateName}
----

[TIP]
====
See link:#rest_v2_cache_manager_cache_templates[Listing Available Cache Templates].
====

[id='rest_v2_cache_configuration']
= Retrieving Cache Configuration
Retrieve {brandname} cache configurations with `GET` requests.

[source,options="nowrap",subs=attributes+]
----
GET /rest/v2/caches/{name}?action=config
----

.Headers

|===
|Header |Required or Optional |Parameter

|`Accept`
|OPTIONAL
|Sets the required format to return content. Supported formats are `application/xml` and `application/json`. The default is `application/json`. See link:#rest_accept[Accept] for more information.
|===

[id='rest_v2_cache_config_convert']
= Converting Cache Configurations between XML, JSON and YAML
Invoke a `POST` request with valid configuration and the `?action=convert`
parameter. {brandname} responds with the equivalent representation of the
configuration in the type specified by the `Accept` header.

[source,options="nowrap",subs=attributes+]
----
POST /rest/v2/caches?action=convert
----

To convert cache configuration you must specify the input format for the configuration with the `Content-Type` header and the desired output format with the `Accept` header.
For example, the following command converts the replicated cache configuration from XML to YAML:

[source,options="nowrap",subs=attributes+]
----
curl localhost:11222/rest/v2/caches?action=convert \
--digest -u username:password \
-X POST -H "Accept: application/yaml" -H "Content-Type: application/xml" \
-d '<replicated-cache mode="SYNC" statistics="false"><encoding media-type="application/x-protostream"/><expiration lifespan="300000" /><memory max-size="400MB" when-full="REMOVE"/></replicated-cache>'
----

[id='rest_v2_cache_config_compare']
= Comparing Cache Configurations
Invoke a `POST` request with a `multipart/form-data` body containing two cache configurations and the `?action=compare`
parameter.

[source,options="nowrap",subs=attributes+]
----
POST /rest/v2/caches?action=compare
----

TIP: Add the `ignoreMutable=true` parameter to ignore mutable attributes in the comparison.

{brandname} responds with `204 (No Content)` in case the configurations are equal, and `409 (Conflict)` in case they are different.

[id='rest_v2_cache_detail']
= Retrieving All Cache Details
Invoke a `GET` request to retrieve all details for {brandname} caches.

[source,options="nowrap",subs=attributes+]
----
GET /rest/v2/caches/{name}?action=stats
----

{brandname} provides a JSON response such as the following:

[source,json,options="nowrap",subs=attributes+]
----
include::json/rest_full_cache_detail.json[]
----

* `stats` current stats of the cache.
* `size` the estimated size for the cache.
* `configuration` the cache configuration.
* `rehash_in_progress` true when a rehashing is in progress.
* `indexing_in_progress` true when indexing is in progress.
* `rebalancing_enabled` is true if rebalancing is enabled. Fetching this property might fail on the server. In that case the property won't be present in the payload.
* `bounded` when expiration is enabled.
* `indexed` true if the cache is indexed.
* `persistent` true if the cache is persisted.
* `transactional` true if the cache is transactional.
* `secured` true if the cache is secured.
* `has_remote_backup` true if the cache has remote backups.
* `key_storage` the media type of the cache keys.
* `value_storage` the media type of the cache values.

[NOTE]
`key_storage` and `value_storage` matches encoding configuration of the cache.
For server caches with no encoding, {brandname} assumes `application/x-protostream` when a cache is indexed and `application/unknown` otherwise.

[id='rest_v2_cache_reset_stats']
= Resetting All Cache Statistics
Invoke a `POST` request to reset all statistics for {brandname} caches.

[source,options="nowrap",subs=attributes+]
----
POST /rest/v2/caches/{name}?action=stats-reset
----

[id='rest_v2_cache_distribution']
= Retrieving Data Distribution of a Cache

Invoke a `GET` request to retrieve all details for data distribution of {brandname} caches.

[source,options="nowrap",subs=attributes+]
----
GET /rest/v2/caches/{name}?action=distribution
----

{brandname} provides a JSON response such as the following:

[source,json,options="nowrap",subs=attributes+]
----
include::json/rest_full_cache_data_distribution.json[]
----

Each element in the list represents a node. The properties are:

* `node_name` is the node name
* `node_addresses` is a list with all the node's physical addresses.
* `memory_entries` the number of entries the node holds in memory belonging to the cache.
* `total_entries` the number of entries the node has in memory and disk belonging to the cache.
* `memory_used` the value in bytes the eviction algorithm estimates the cache occupies. Returns -1 if eviction is not enabled.

[id='rest_v2_cache_mutable_attributes']
= Retrieving all mutable cache configuration attributes
Invoke a `GET` request to retrieve all mutable cache configuration attributes for {brandname} caches.

[source,options="nowrap",subs=attributes+]
----
GET /rest/v2/caches/{name}?action=get-mutable-attributes
----

{brandname} provides a JSON response such as the following:

[source,json,options="nowrap",subs=attributes+]
----
include::json/rest_cache_mutable_attributes.json[]
----

Add the `full` parameter to obtain values and type information:

[source,options="nowrap",subs=attributes+]
----
GET /rest/v2/caches/mycache?action=get-mutable-attributes&full=true
----

{brandname} provides a JSON response such as the following:

[source,json,options="nowrap",subs=attributes+]
----
include::json/rest_cache_mutable_attributes_full.json[]
----

For attributes of type `enum`, an additional `universe` property will contain the set of possible values.

[id='rest_v2_cache_mutable_attribute_set']
= Updating cache configuration attributes
Invoke a `POST` request to change a mutable cache configuration attribute.

[source,options="nowrap",subs=attributes+]
----
POST /rest/v2/caches/{name}?action=set-mutable-attributes&attribute-name={attributeName}&attribute-value={attributeValue}
----

[id='rest_v2_add_entries']
= Adding Entries
Add entries to caches with `POST` requests.

[source,options="nowrap",subs=attributes+]
----
POST /rest/v2/caches/{cacheName}/{cacheKey}
----

The preceding request places the payload, or request body, in the `cacheName`
cache with the `cacheKey` key. The request replaces any data that already
exists and updates the `Time-To-Live` and `Last-Modified` values, if they apply.

If the entry is created successfully, the service returns `204 (No Content)`.

If a value already exists for the specified key, the `POST` request returns
`409 (Conflict)` and does not modify the value.
To update values, you
should use `PUT` requests. See link:#rest_v2_replace_entries[Replacing Entries].

.Headers

|===
|Header |Required or Optional |Parameter

|`Key-Content-Type`
|OPTIONAL
|Sets the content type for the key in the request. See link:#rest_key_content_type[Key-Content-Type] for more information.

|`Content-Type`
|OPTIONAL
|Sets the link:https://en.wikipedia.org/wiki/Media_type[MediaType] of the value for the key.

|`timeToLiveSeconds`
|OPTIONAL
|Sets the number of seconds before the entry is automatically deleted. If you do not set this parameter, {brandname} uses the default value from the configuration. If you set a negative value, the entry is never deleted.

|`maxIdleTimeSeconds`
|OPTIONAL
|Sets the number of seconds that entries can be idle. If a read or write operation does not occur for an entry after the maximum idle time elapses, the entry is automatically deleted. If you do not set this parameter, {brandname} uses the default value from the configuration. If you set a negative value, the entry is never deleted.

|`flags`
|OPTIONAL
|The flags used to add the entry. See https://docs.jboss.org/infinispan/10.0/apidocs/org/infinispan/context/Flag.html[Flag] for more information.

|===

[NOTE]
The `flags` header also applies to all other operations involving data manipulation on the cache,

[NOTE]
====
If both `timeToLiveSeconds` and `maxIdleTimeSeconds` have a value of `0`, {brandname} uses the default `lifespan` and `maxIdle` values from the configuration.

If _only_ `maxIdleTimeSeconds` has a value of `0`, {brandname} uses:

* the default `maxIdle` value from the configuration.
* the value for `timeToLiveSeconds` that you pass as a request parameter or a value of `-1` if you do not pass a value.

If _only_ `timeToLiveSeconds` has a value of `0`, {brandname} uses:

* the default `lifespan` value from the configuration.
* the value for `maxIdle` that you pass as a request parameter or a value of `-1` if you do not pass a value.
====


[id='rest_v2_replace_entries']
= Replacing Entries
Replace entries in caches with `PUT` requests.

[source,options="nowrap",subs=attributes+]
----
PUT /rest/v2/caches/{cacheName}/{cacheKey}
----

If a value already exists for the specified key, the `PUT` request updates the
value. If you do not want to modify existing values, use `POST` requests that
return `409 (Conflict)` instead of modifying values. See
link:#rest_v2_add_entries[Adding Values].

[id='rest_v2_retrieve_cache']
= Retrieving Data By Keys
Retrieve data for specific keys with `GET` requests.

[source,options="nowrap",subs=attributes+]
----
GET /rest/v2/caches/{cacheName}/{cacheKey}
----

The server returns data from the given cache, `cacheName`, under the given key,
`cacheKey`, in the response body. Responses contain `Content-Type` headers that
correspond to the `MediaType` negotiation.

[NOTE]
====
Browsers can also access caches directly, for example as a content delivery
network (CDN). {brandname} returns a unique
link:http://en.wikipedia.org/wiki/HTTP_ETag[ETag] for each entry along with the
`Last-Modified` and `Expires` header fields.

These fields provide information about the state of the data that is returned
in your request. ETags allow browsers and other clients to request only data
that has changed, which conserves bandwidth.
====

.Headers

|===
|Header |Required or Optional |Parameter

|`Key-Content-Type`
|OPTIONAL
|Sets the content type for the key in the request. The default is `application/x-java-object; type=java.lang.String`. See link:#rest_key_content_type[Key-Content-Type] for more information.

|`Accept`
|OPTIONAL
|Sets the required format to return content. See link:#rest_accept[Accept] for more information.
|===

[TIP]
====
Append the `extended` parameter to the query string to get additional information:

[source,options="nowrap",subs=attributes+]
----
GET /rest/v2/caches/{cacheName}/{cacheKey}?extended
----

The preceding request returns custom headers:

* `Cluster-Primary-Owner` returns the node name that is the primary owner of the key.
* `Cluster-Node-Name` returns the JGroups node name of the server that handled the request.
* `Cluster-Physical-Address` returns the physical JGroups address of the server that handled the request.
====


[id='rest_v2_check_entries']
= Checking if Entries Exist
Verify that specific entries exists with `HEAD` requests.

[source,options="nowrap",subs=attributes+]
----
HEAD /rest/v2/caches/{cacheName}/{cacheKey}
----

The preceding request returns only the header fields and the same content that
you stored with the entry. For example, if you stored a String, the request
returns a String. If you stored binary, base64-encoded, blobs or serialized
Java objects, {brandname} does not de-serialize the content in the request.

[NOTE]
====
`HEAD` requests also support the `extended` parameter.
====

.Headers
|===
|Header |Required or Optional |Parameter

|`Key-Content-Type`
|OPTIONAL
|Sets the content type for the key in the request. The default is `application/x-java-object; type=java.lang.String`. See link:#rest_key_content_type[Key-Content-Type] for more information.
|===


[id='rest_v2_delete_entries']
= Deleting Entries
Remove entries from caches with `DELETE` requests.

[source,options="nowrap",subs=attributes+]
----
DELETE /rest/v2/caches/{cacheName}/{cacheKey}
----

.Headers

|===
|Header |Required or Optional |Parameter

|`Key-Content-Type`
|OPTIONAL
|Sets the content type for the key in the request. The default is `application/x-java-object; type=java.lang.String`. See link:#rest_key_content_type[Key-Content-Type] for more information.
|===

[id='rest_v2_distribution_entries']
= Checking distribution of cache entries
Invoke this endpoint to retrieve details for data distribution of {brandname} cache entry.

[source,options="nowrap",subs=attributes+]
----
GET /rest/v2/caches/{cacheName}/{cacheKey}?action=distribution
----

{brandname} provides a JSON response such as the following:

[source,json,options="nowrap",subs=attributes+]
----
include::json/rest_full_key_data_distribution.json[]
----

* `contains_key` returns `true` if the cache contains the key
* `owners` provides a list of nodes that contain the key

List of owners includes the following properties:

* `node_name` shows the name of the node
* `primary` identifies a node that is the primary owner
* `node_addresses` shows the IP addresses and ports where the node can be accessed

[id='rest_v2_remove_cache']
= Deleting Caches
Remove caches from {brandname} clusters with `DELETE` requests.

[source,options="nowrap",subs=attributes+]
----
DELETE /rest/v2/caches/{cacheName}
----


[id='rest_v2_get_keys']
= Retrieving All Keys from Caches
Invoke `GET` requests to retrieve all the keys in a cache in JSON format.

[source,options="nowrap",subs=attributes+]
----
GET /rest/v2/caches/{cacheName}?action=keys
----

.Request Parameters

|===
|Parameter |Required or Optional |Value

|`limit`
|OPTIONAL
|Specifies the maximum number of keys to retrieve using an InputStream. A negative value retrieves all keys. The default value is `-1`.
|`batch`
|OPTIONAL
|Specifies the internal batch size when retrieving the keys. The default value is `1000`.
|===

[id='rest_v2_get_entries']
= Retrieving All Entries from Caches
Invoke `GET` requests to retrieve all the entries in a cache in JSON format.

[source,options="nowrap",subs=attributes+]
----
GET /rest/v2/caches/{cacheName}?action=entries
----

.Request Parameters

|===
|Parameter |Required or Optional |Value

|`metadata`
|OPTIONAL
|Includes metadata for each entry in the response. The default value is `false`.
|`limit`
|OPTIONAL
|Specifies the maximum number of keys to include in the response. A negative value retrieves all keys. The default value is `-1`.
|`batch`
|OPTIONAL
|Specifies the internal batch size when retrieving the keys. The default value is `1000`.
|`content-negotiation`
|OPTIONAL
| If `true`, will convert keys and values to a readable format.
For caches with text encodings (e.g., text/plain, xml, json), the server returns keys and values as plain text.
For caches with binary encodings, the server will return the entries as JSON if the conversion is supported, otherwise in a text hexadecimal format, e.g., `0xA123CF98`.
When content-negotiation is used, the response will contain two headers: `key-content-type` and `value-content-type` to described the negotiated format.
|===

{brandname} provides a JSON response such as the following:

[source,json,options="nowrap",subs=attributes+]
----
include::json/rest_caches_all_entries.json[]
----

* `key` The key for the entry.
* `value` The value of the entry.
* `timeToLiveSeconds` Based on the entry lifespan but in seconds, or `-1` if the entry never expires. It's not returned unless you set metadata="true".
* `maxIdleTimeSeconds` Maximum idle time, in seconds, or `-1` if entry never expires. It's not returned unless you set metadata="true".
* `created` Time the entry was created or or `-1` for immortal entries. It's not returned unless you set metadata="true".
* `lastUsed` Last time an operation was performed on the entry or `-1` for immortal entries. It's not returned unless you set metadata="true".
* `expireTime` Time when the entry expires or `-1` for immortal entries. It's not returned unless you set metadata="true".
* `version` The metadata version related to the cache entry. Only if the value is present.
* `topologyId` The topology Id of a clustered version metadata. Only if the value is present.

[id='rest_v2_clear_cache']
= Clearing Caches

To delete all data from a cache, invoke a `POST` request with the
`?action=clear` parameter.

[source,options="nowrap",subs=attributes+]
----
POST /rest/v2/caches/{cacheName}?action=clear
----

If the operation successfully completes, the service returns `204 (No Content)`.

[id='rest_v2_cache_size']
= Getting Cache Size
Retrieve the size of caches across the entire cluster with `GET` requests and
the `?action=size` parameter.

[source,options="nowrap",subs=attributes+]
----
GET /rest/v2/caches/{cacheName}?action=size
----


[id='rest_v2_cache_stats']
= Getting Cache Statistics
Obtain runtime statistics for caches with `GET` requests.

[source,options="nowrap",subs=attributes+]
----
GET /rest/v2/caches/{cacheName}?action=stats
----

[id='rest_v2_list_caches']
= Listing Caches
List all available caches in {brandname} clusters with `GET` requests.

[source,options="nowrap",subs=attributes+]
----
GET /rest/v2/caches/
----


[id='rest_v2_cache_list_detailed']
= Obtaining Caches Status and Information
Retrieve a list of all available caches for the cache manager, along with cache statuses and details, with `GET` requests.

[source,options="nowrap",subs=attributes+]
----
GET /rest/v2/caches?action=detailed
----

{brandname} responds with JSON arrays that lists and describes each available
cache, as in the following example:

[source,json,options="nowrap",subs=attributes+]
----
include::json/rest_caches_info_response.json[]
----

.Request parameters

|===
|Parameter |Required or Optional |Description

|`pretty`
|OPTIONAL
|If `true` returns formatted content, including additional spacing and line separators which improve readability but increase payload size. The default is `false`.

|===


[id='rest_v2_list_caches_by_role']
= Listing accessible caches for a role
When security is enabled, retrieve a list of all the accessible caches for a role.
This operation requires ADMIN permission.

[source,options="nowrap",subs=attributes+]
----
GET /rest/v2/caches?action=role-accessible&role=observer
----

{brandname} responds with JSON as in the following example:

[source,json,options="nowrap",subs=attributes+]
----
include::json/rest_caches_accessible_role_response.json[]
----

.Request parameters

|===
|Parameter |Required or Optional |Description

|`pretty`
|OPTIONAL
|If `true` returns formatted content, including additional spacing and line separators which improve readability but increase payload size. The default is `false`.

|===

[id='rest_v2_cache_listen']
= Listening to cache events
Receive cache events using https://html.spec.whatwg.org/multipage/server-sent-events.html[Server-Sent Events].
The `event` value will be one of `cache-entry-created`, `cache-entry-removed`, `cache-entry-updated`, `cache-entry-expired`.
The `data` value will contain the key of the entry that has fired the event in the format set by the `Accept` header.

[source,options="nowrap",subs=attributes+]
----
GET /rest/v2/caches/{name}?action=listen
----

.Headers

|===
|Header |Required or Optional |Parameter

|`Accept`
|OPTIONAL
|Sets the required format to return content. Supported formats are `text/plain` and `application/json`. The default is `application/json`. See link:#rest_accept[Accept] for more information.
|===

[id='rest_v2_caches_enable_rebalancing']
= Enabling rebalancing
Turn on automatic rebalancing for a specific cache.

[source,options="nowrap",subs=attributes+]
----
POST /rest/v2/caches/{cacheName}?action=enable-rebalancing
----

[id='rest_v2_caches_disable_rebalancing']
= Disabling rebalancing
Turn off automatic rebalancing for a specific cache.

[source,options="nowrap",subs=attributes+]
----
POST /rest/v2/caches/{cacheName}?action=disable-rebalancing
----

[id='rest_v2_caches_get_availability']
= Getting Cache Availability
Retrieve the availability of a cache.

[source,options="nowrap",subs=attributes+]
----
GET /rest/v2/caches/{cacheName}?action=get-availability
----

[NOTE]
You can get the availability of internal caches but this is subject to change in future {brandname} versions.

[id='rest_v2_caches_set_availability']
= Setting Cache Availability
Change the availability of clustered caches when using either the DENY_READ_WRITES or ALLOW_READS partition handling strategy.

[source,options="nowrap",subs=attributes+]
----
POST /rest/v2/caches/{cacheName}?action=set-availability&availability={AVAILABILITY}
----

.Request Parameters

|===
|Parameter |Required or Optional |Value

|`availability`
|REQUIRED
|AVAILABLE or DEGRADED_MODE
|===

* `AVAILABLE` makes caches available to all nodes in a network partition.
* `DEGRADED_MODE` prevents read and write operations on caches when network partitions occur.

[NOTE]
You can set the availability of internal caches but this is subject to change in future {brandname} versions.

[id='rest_v2_caches_set_topology_stable']
= Set a Stable Topology
By default, after a cluster shutdown, {brandname} waits for all nodes to join the cluster and restore the topology.
However, you can define the current cluster topology as stable for a specific cache using a REST operation.

[source,options="nowrap",subs=attributes+]
----
POST /rest/v2/caches/{cacheName}?action=initialize&force={FORCE}
----

.Request Parameters

|===
|Parameter |Required or Optional |Value

|`force`
|OPTIONAL
|true or false.
|===

* `force` is required when the number of missing nodes in the current topology is greater or equal to the number of owners.

[IMPORTANT]
====
Manually installing a topology can lead to data loss, only perform this operation if the initial topology cannot be recreated.
====
