Using the Infinispan REST Endpoint

A PUT request of the above URL form will place the payload (body) in the given cache, with the given key (the named cache must exist on the server). For example http://someserver/hr/payRoll-3 (in which case hr is the cache name, and payRoll-3 is the key). Any existing data will be replaced, and Time-To-Live and Last-Modified values etc will updated (if applicable).

Exactly the same as PUT, only if a value in a cache/key already exists, it will return a Http CONFLICT status (and the content will not be updated).

This will return the data found in the given cacheName, under the given key - as the body of the response. A Content-Type header will be present in the response according to the Media Type negotiation. Browsers can use the cache directly of course (eg as a CDN). An ETag will be returned unique for each entry, as will the Last-Modified and Expires headers field indicating the state of the data at the given URL. ETags allow browsers (and other clients) to ask for data only in the case where it has changed (to save on bandwidth) - this is standard HTTP and is honoured by Infinispan.

It is possible to obtain additional information by appending the "extended" parameter on the query string, as follows:

GET /rest/cacheName/cacheKey?extended

This will return the following custom headers:

The same as GET, only no content is returned (only the header fields). You will receive the same content that you stored. E.g., if you stored a String, this is what you get back. If you stored some XML or JSON, this is what you will receive. If you stored a binary (base 64 encoded) blob, perhaps a serialized; Java; object - you will need to; deserialize this yourself.

Similarly to the GET method, the HEAD method also supports returning extended information via headers. See above.

This will return a list of keys present in the given cacheName as the body of the response. The format of the response can be controlled via the Accept header as follows:

If the cache identified by cacheName is distributed, only the keys owned by the node handling the request will be returned. To return all keys, append the "global" parameter to the query, as follows:

GET /rest/cacheName?global

Removes the given key name from the cache.

Removes ALL the entries in the given cache name (i.e., everything from that path down). If the operation is successful, it returns 200 code.

Will execute an Ickle query in the given cache name.

Results are JSON documents containing one or more hits. Example:

Similar to que query using GET, but the body of the request is used instead to specify the query parameters.

Example:

To create a named cache across the Infinispan cluster, invoke a POST request:

To configure the cache, you supply the configuration in XML or JSON format as part of the request payload.

To retrieve the configuration of a Infinispan cache, invoke a GET request:

To add entries to a named cache, invoke a POST request:

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 a value already exists for the specified key, the POST request returns an HTTP CONFLICT status and does not modify the value. To update values, you should use PUT requests. See Replacing Entries.

To replace entries in a named cache, invoke a PUT request:

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 HTTP CONFLICT status instead of modifying values. See Adding Values.

To retrieve data for a specific key in a cache, invoke a GET request:

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.

To check if a specific entry exists in a cache, invoke a HEAD request:

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, Infinispan does not de-serialize the content in the request.

HEAD requests also support the extended parameter.

To delete entries from a cache, invoke a DELETE request:

Infinispan removes the entry under cacheKey from the cache.

To remove caches, invoke a DELETE request:

Infinispan deletes all data and removes the cache named cacheName from the cluster.

To obtain all the keys from the cache in JSON format, invoke a GET request:

To delete all data from a cache, invoke a GET request with the ?action=clear parameter:

To obtain the size of a cache across the entire cluster, invoke a GET request with the ?action=size parameter:

To obtain runtime statistics of a cache invoke a GET request:

Invoke a GET request to perform and Ickle query on a given cache:

Infinispan returns one or more query hits in JSON format, for example:

To use the body of the request instead of specifying query parameters, invoke a POST request:

The following example shows a query in the request body:

To obtain a list of caches available in a Infinispan cluster, invoke a GET request:

Use the REST API to monitor and control Cross Site (x-site) replication on your Infinispan cluster. See Cross Site replication for more details about this feature.

To obtain information about a cache manager, invoke a GET request:

Infinispan responds with a JSON document such as the following:

To review health information for a Infinispan cluster, invoke a GET request:

Infinispan responds with a JSON document such as the following:

To check that a Infinispan server REST endpoint is available, invoke a HEAD request in the health resource:

If the preceding request returns a successful response code then the Infinispan REST server is running and serving requests.

To obtain the GlobalConfiguration associated with the Cache Manager, invoke a GET request:

To get the configuration for all caches, invoke a GET request:

Infinispan responds with a JSON array that contains each cache and cache configuration:

To obtain the statistics of a Cache Manager, invoke a GET request.

Infinispan responds with a JSON document that contains the following information:

To create a counter, invoke a POST request with the configuration as payload:

The payload must contain a configuration for the counter in JSON format, as in the following examples:

To delete a counter, invoke a DELETE request with the counter name:

The get the counter configuration, invoke a GET request with the counter name:

Infinispan responds with a JSON representation of the counter configuration.

To add a value to a named counter, invoke a POST request:

If the request payload is empty, the counter is incremented by one, otherwise the payload is interpreted as a signed long and added to the counter.

Request responses depend on the type of counter, as follows:

To retrieve the value of a counter, invoke a GET request:

To reset counters, invoke a GET request with the ?action=reset parameter:

To increment a counter, invoke a GET request with the ?action=increment parameter:

Responses depend on the type of counter, as follows:

To add an arbitrary amount to a counter, invoke a GET request with the ?action=add and delta parameters:

Request responses depend on the type of counter, as follows:

To decrement a counter, invoke a GET request with the ?action=decrement parameter:

Request responses depend on the type of counter, as follows:

To atomically set the value of a strong counter with the compareAndSet method, invoke a GET request:

Infinispan atomically sets the value to {update} if the current value is {expect}. If the operation is successful, Infinispan returns true.

To atomically set the value of a strong counter with the compareAndSwap method, invoke a GET request:

Infinispan atomically sets the value to {update} if the current value is {expect}. If the operation is successful, Infinispan returns the previous value in the payload.

To obtain a list of counters available in a Infinispan cluster, invoke a GET request:

To view basic information about a Infinispan server, invoke a GET request:

The response contains the server name, codename, and version in JSON format, as in the following example:

To obtain the list of the server’s cache managers:

The response will contain an array with the names of the cache managers configured in the server.

A cache can be excluded temporarily from receiving requests from clients, returning a code 503 (service unavailable) for REST clients or a Server Error (code 0x85) for Hot Rod clients.

To ignore a cache, use an empty POST request with the cache manager name and the cache name:

To remove the cache from the ignore list, use a DELETE request:

Finally, to check the caches that are ignored, do a GET request:

To get the configuration for a Infinispan server, invoke a GET request:

The server responds with the configuration in JSON format. The structure follows the server schema, as in the following example:

To get environment variables that the server uses, invoke a GET request:

To get information about JVM memory usage, invoke a GET request:

The server responds with heap and non-heap memory statistics, direct memory usage, and information about memory pools and garbage collection in JSON format.

To get the current thread dump for the JVM, invoke a GET request:

The response is the current thread dump in text/plain format.

To stop a Infinispan server, invoke a GET request:

The server responds with 200(OK) and then stops running.