JBoss Community Archive (Read Only)

Infinispan 6.0

Accessing data in Infinispan via RESTful interface

images/author/download/attachments/3737132/reststar_icon_64x.png Standards Red Hat is working towards standardization of the REST API as a part of the REST-* effort.  To participate in this standard, please visit this Google Group

Putting data in

HTTP PUT and POST methods are used to place data in the cache - the data being the body of the request (the data can be anything you like). It is important that a Content-Type header is set.

PUT /{cacheName}/{cacheKey}

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).

POST /{cacheName}/{cacheKey}

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).


  • Content-Type: MANDATORY (use media/mime-types for example: "application/json").

    Special case

    If you set the Content-Type to application/x-java-serialized-object, then it will be stored as a Java object

  • performAsync: OPTIONAL true/false (if true, this will return immediately, and then replicate data to the cluster on its own. Can help with bulk data inserts/large clusters.)

  • timeToLiveSeconds: OPTIONAL number (the number of seconds before this entry will automatically be deleted)

    • If no parameter is sent, Infinispan assumes -1 as default value, which means that the entry will not expire as a result of ttl. Passing any negative value will have the same effect.

  • maxIdleTimeSeconds: OPTIONAL number (the number of seconds after last usage of this entry when it will automatically be deleted)

    • If no parameter is sent, Infinispan assumes -1 as default value, which means that the entry will not expire as a result of idle time. Passing any negative value will have the same effect.

Passing 0 as parameter for timeToLiveSeconds and/or maxIdleTimeSeconds
  • If both timeToLiveSeconds and maxIdleTimeSeconds are 0, the cache will use the default lifespan and maxIdle values configured in XML/programmatically

  • If only maxIdleTimeSeconds is 0, it uses the timeToLiveSeconds value passed as parameter (or -1 if not present), and default maxIdle configured in XML/programmatically

  • If only timeToLiveSeconds is 0, it uses 0 as timeToLiveSeconds meaning that it will expire immediately, and maxIdle is set whatever came as parameter (or -1 if not present)

Getting data back out

HTTP GET and HEAD are used to retrieve data from entries.

GET /{cacheName}/{cacheKey}

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 supplied which matches what the data was inserted as (other then if it is a Java object, see below). 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.

Since Infinispan 5.3 it is possible to obtain additional information by appending the "extended" parameter on the query string, as follows:

GET /cacheName/cacheKey?extended

This will return the following custom headers:

  • Cluster-Primary-Owner: the node name of the primary owner for this key

  • Cluster-Node-Name: the JGroups node name of the server that has handled the request

  • Cluster-Physical-Address: the physical JGroups address of the server that has handled the request.

Since version 6.0, the Cache-Control header is supported. The min-fresh directive of this header can be supplied with a request. A cache entry will then only be returned if it won't expire in min-fresh seconds since the response creation. A response might contain Cache-Control header with no-transform and max-age directives. The max-age directive is similar to Expires in that is signifies entry's lifespan. The only difference is that max-age returns number of seconds relative to the response creation time.

HEAD /{cacheName}/{cacheKey}

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.

Prior to Infinispan 4.2

The behaviour was as follows:
If the data in the grid is a Java object - there are a few options in how it can be returned, which use the HTTP Accept header:

  • application/xml - the object will be serialized via XStream to XML representation

  • application/json - the object will be sent via a JSON format (via Jackson)

  • application/x-java-serialized-object - if the object is Serializable, you can use this and get a stream of the Java Serialization form of the object (obviously only makes sense for java clients with a suitable class loaded). If its not Serializable, you have to use one of the other options.

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

GET /{cacheName}

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:

  • application/xml - the list of keys will be returned in XML format.

  • application/json - the list of keys will be return in JSON format.

  • text/html - the list of keys will be returned in HTML format.

  • text/plain - the list of keys will be returned in plain text format, one key per line

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 /cacheName?global

Removing data

Data can be removed at the cache key/element level, or via a whole cache name using the HTTP delete method.

DELETE /{cacheName}/{cacheKey}

Removes the given key name from the cache.

DELETE /{cacheName}

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

Make it quicker!

Set the header performAsync to true to return immediately and let the removal happen in the background.

JBoss.org Content Archive (Read Only), exported from JBoss Community Documentation Editor at 2020-03-11 09:39:15 UTC, last content change 2013-09-04 16:05:44 UTC.