Welcome to the Infinispan REST Server
This server provides easy to use RESTful access to the Infinispan data grid. See below for usage details.
1. Configuration
Out of the box, Infinispan will use its local mode cache. To set a custom configuration, create an Infinispan XML configuration file and set the PATH to it in your web.xml file, under the key infinispan.config. See the sample web.xml file for details. The value should be a path to your config file.
Please note that the REST server only allows interaction with either the default cache, named ___defaultcache or one of the named caches in the configuration file. This is because the REST server starts default and pre-defined caches on startup in order to provide a more consistent behaivour. So, if you don't pass any configuration file, you'll only be able to interact with the default cache. To interact with more caches, pass a configuration file with the desired named caches.
This chapter in the Infinispan user guide has more details.
2. 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 (if the cache name is new, it will be automatically initialised). 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 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).
Headers:
The following HTTP headers are supported:
| Header Name | Required? | Description |
|---|---|---|
| Content-Type | Yes | Use media/mime-types, for example "application/json" |
| timeToLiveSeconds | No | The number of seconds before this entry will automatically be deleted |
| maxIdleTimeSeconds | No | The number of seconds after last usage of this entry when it will automatically be deleted |
| performAsync | No | If true, this will return immediately, and then replicate data to the cluster on its own. Can help with bulk data inserts/large clusters. |
3. 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 cache name, 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. Browsers can use the cache directly of course (e.g., as a CDN).
An ETag will be returned unique for each entry, as will the Last-Modified header 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 honored by Infinispan.
HEAD /{cacheName}/{cacheKey}
The same as GET, only no content is returned (only the header fields).
4. 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).
OPTIONAL: Set the header performAsync to true to return immediately and let the removal happen in the background.
5. Clients
Any HTTP client will do - from any language. See here for more details.6. Deployment
As Infinispan is a distributed data grid, it shouldn't matter how many or which instance of the Server you access, as long as it is part of the Infinispan cluster, it will find your data, and manage it. You can have as many instances (including the one you are looking at) as you need.6. Further reading
Please visit Infinispan's public wiki for more information including a full user guide, frequently asked questions, tutorials, demos and examples, and other resources.