Chapter 13. The REST API

The REST API exposes caches that store data in a format defined by a configurable media type.

The following XML snippet shows an example configuration that defines the media type for keys and values:

<cache>
   <encoding>
      <key media-type="application/x-java-object; type=java.lang.Integer"/>
      <value media-type="application/xml; charset=UTF-8"/>
   </encoding>
</cache>

For more information, see Configuring Media Types.

Calls to the Red Hat JBoss Data Grid REST API can provide headers that describe:

JBoss Data Grid supports the HTTP/1.1 Content-Type and Accept headers applied to values as well as the Key-Content-Type header for keys.

The Red Hat JBoss Data Grid REST server complies with the RFC-2616 specification for Accept headers and negotiates the correct media type based on the supported conversions.

For example, a client sends the following header in a call to read data from the cache:

Accept: text/plain;q=0.7, application/json;q=0.8, */*;q=0.6

In this case, JBoss Data Grid gives precedence to JSON format during negotiation because that media type has highest priority (0.8). If the server does not support JSON format, text/plain takes precedence because the media type has the next highest priority (0.7).

In the event that the server does not support either the JSON or text/plain media types, / takes precedence, which indicates any suitable media type based on the cache configuration.

When the negotiation completes, the server continues using the chosen media type for the operation. If any errors occur during the operation, the server does not attempt to use any other media type.

Most calls to the REST API include the key in the URL. When handling those calls, Red Hat JBoss Data Grid uses the java.lang.String as the content type for keys by default. However, you can use the Key-Content-Type header to specify different content types for keys.

Add data to the cache with the following methods:

When you call the REST API with the PUT and POST methods, the body of the request contains the data.

A PUT request from the provided URL form places the payload, from the request body in the targeted cache using the provided key. The targeted cache must exist on the server for this task to successfully complete.

As an example, in the following URL, the value hr is the cache name and payRoll%2F3 is the key. The value %2F indicates that a / character was used in the key.

http://someserver/rest/hr/payRoll%2F3

Any existing data is replaced and Time-To-Live and Last-Modified values are updated, if required.

-Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true

The POST method from the provided URL form places the payload (from the request body) in the targeted cache using the provided key. However, in a POST method, if a value in a cache/key exists, a HTTP CONFLICT status is returned and the content is not updated.

The following combinations can be set for the timeToLiveSeconds and maxIdleTimeSeconds headers:

Retrieve data from the cache with the following methods:

The GET method returns the data located in the supplied cacheName, matched to the relevant key, as the body of the response. The Content-Type header provides the type of the data. A browser can directly access the cache.

A unique entity tag (ETag) is returned for each entry along with a Last-Modified header which indicates the state of the data at the requested URL. ETags allow browsers (and other clients) to ask for data only in the case where it has changed (to save on bandwidth). ETag is a part of the HTTP standard and is supported by Red Hat JBoss Data Grid.

The type of content stored is the type returned. As an example, if a String was stored, a String is returned. An object which was stored in a serialized form must be manually deserialized.

Appending the extended parameter to the query returns additional information. For example,

GET /{cacheName}/{cacheKey}?extended

Returns the following custom headers:

The HEAD method operates in a manner similar to the GET method, however returns no content (header fields are returned).

The GET method can return a list of keys that reside in the cache. The list of keys is returned in the body of the response.

The Accept header can format the response as follows:

If the cache is distributed then only keys that are owned by the node that handles the request are returned. To return all keys, append the global parameter to the query as follows:

GET /{cacheName}?global

Remove data from Red Hat JBoss Data Grid with the HTTP DELETE method.

The DELETE method can:

Used in this context (DELETE /{cacheName}/{cacheKey}), the DELETE method removes the key/value from the cache for the provided key.

In this context (DELETE /{cacheName}), the DELETE method removes all entries in the named cache. After a successful DELETE operation, the HTTP status code 200 is returned.

Set the value of the performAsync header to true to ensure an immediate return while the removal operation continues in the background.

JBoss Data Grid uses protocol buffers to efficiently store data in binary format in the cache while exposing queries and enabling you to read and write content in JSON format.

To store Protobuf encoded entries, the cache must be configured with the application/x-protostream media type. JBoss Data Grid then automatically converts JSON to Protobuf.

If the cache is indexed, you do not need to perform any configuration. By default, an indexed cache stores entries with the application/x-protostream media type.

However, if the cache is not indexed, you must configure keys and values with the application/x-protostream media type, as in the following example:

<cache>
   <encoding>
      <key media-type="application/x-protostream"/>
      <value media-type="application/x-protostream"/>
   </encoding>
</cache>

To register a Protobuf schema, you can use the HTTP POST method to insert the schema in the ___protobuf_metadata cache, as in the following example:

curl -u user:password -X POST --data-binary @./schema.proto http://127.0.0.1:8080/rest/___protobuf_metadata/schema.proto

For more information about Protobuf encoding and registering Protobuf schemas, see Protobuf Encoding.

The _type field must be included in JSON documents. This field identifies the Protobuf message to which the JSON document corresponds.

For example, the following is a Protobuf message defined as Person:

message Person {
  required string name = 1;
  required int32 age = 2;
}

The corresponding JSON document is as follows:

{
  "_type": "Person",
  "name": "user1",
  "age": 32
}

You can write content to the cache in JSON format as follows:

curl -u user:user -XPOST --data-binary @./Person.json -H "Content-Type: application/json; charset=UTF-8" http://127.0.0.1:8080/rest/{cacheName}/{key}

After you write content to the cache, you can read it in JSON format as follows:

curl -u user:user http://127.0.0.1:8080/rest/{cacheName}/{key}

Use the HTTP GET method or the POST method to query data via the REST interface.

Query requests with the GET method have the following structure:

{cacheName}?action=search&query={ickle query}

The following are example queries:

Query requests with the POST method have the following structure:

{cacheName}?action=search

The body of the request specifies the query and any parameters in JSON format.

The following is an example query that returns data from the entity named Entity and filters results using a where clause:

{
 "query":"from Entity where name:\"user1\"",
 "max_results":20,
 "offset":10
}

{
  "total_results" : 150,
  "hits" : [ {
    "hit" : {
      "name" : "user1",
      "age" : 35
    }
  }, {
    "hit" : {
       "name" : "user2",
       "age" : 42
    }
  }, {
    "hit" : {
       "name" : "user3",
       "age" : 25
    }
  } ]
}