Chapter 1. Data Grid REST Endpoint

Data Grid servers provide RESTful HTTP access to data through a REST endpoint built on Netty.

1.1. REST Authentication

Configure authentication to the REST endpoint with the Data Grid command line interface (CLI) and the user command. The CLI lets you create and manage users, passwords, and authorization roles for accessing the REST endpoint.

1.2. Supported Protocols

The Data Grid REST endpoint supports HTTP/1.1 and HTTP/2 protocols.

You can do either of the following to use HTTP/2:


TLS/ALPN with JDK8 requires additional client configuration. Refer to the appropriate documentation for your REST client. In most cases you need to use either the Jetty ALPN Agent or OpenSSL bindings.

1.3. Data Formats and the REST API

Data Grid caches store data in formats that you can define with a MediaType.

See the Cache Encoding and Marshalling for more information about MediaTypes and encoding data with Data Grid.

The following example configures the storage format for entries:

      <key media-type="application/x-java-object"/>
      <value media-type="application/xml; charset=UTF-8"/>

If you do not configure a MediaType, Data Grid defaults to application/octet-stream for both keys and values. However, if the cache is indexed, Data Grid defaults to application/x-protostream.

1.3.1. Supported Formats

You can write and read data in different formats and Data Grid can convert between those formats when required.

The following "standard" formats are interchangeable:

  • application/x-java-object
  • application/octet-stream
  • application/x-www-form-urlencoded
  • text/plain

You can also convert the preceding data formats into the following formats:

  • application/xml
  • application/json
  • application/x-jboss-marshalling
  • application/x-protostream
  • application/x-java-serialized

Data Grid also lets you convert between application/x-protostream and application/json.

All calls to the REST API can provide headers describing the content written or the required format of the content when reading. Data Grid supports the standard HTTP/1.1 headers "Content-Type" and "Accept" that are applied for values, plus the "Key-Content-Type" with similar effect for keys.

1.3.2. Accept Headers

The Data Grid REST endpoint is compliant with the RFC-2616 Accept header and negotiates the correct MediaType based on the conversions supported.

For example, send the following header when reading data:

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

The preceding header causes Data Grid to first return content in JSON format (higher priority 0.8). If it is not possible to convert the storage format to JSON, Data Grid attempts the next format of text/plain (second highest priority 0.7). Finally, Data Grid falls back to */*, which picks a suitable format based on the cache configuration.

1.3.3. Names with Special Characters

The creation of any REST resource requires a name that is part of the URL, and in case this name contains any special characters as defined in Section 2.2 of the RFC 3986 spec, it is necessary to encode it with the Percent encoding mechanism.

1.3.4. Key-Content-Type Headers

Most REST API calls have the Key included in the URL. Data Grid assumes the Key is a java.lang.String when handling those calls, but you can use a specific header Key-Content-Type for keys in different formats.

Key-Content-Type Header Examples

  • Specifying a byte[] Key as a Base64 string:

API call:

`PUT /my-cache/AQIDBDM=`


Key-Content-Type: application/octet-stream

  • Specifying a byte[] Key as a hexadecimal string:

API call:

GET /my-cache/0x01CA03042F


Key-Content-Type: application/octet-stream; encoding=hex
  • Specifying a double Key:

API call:

POST /my-cache/3.141456


Key-Content-Type: application/x-java-object;type=java.lang.Double

The type parameter for application/x-java-object is restricted to:

  • Primitive wrapper types
  • java.lang.String
  • Bytes, making application/x-java-object;type=Bytes equivalent to application/octet-stream;encoding=hex.

1.3.5. JSON/Protostream Conversion

When caches are indexed, or specifically configured to store application/x-protostream, you can send and receive JSON documents that are automatically converted to and from Protobuf.

You must register a Protobuf schema for the conversion to work.

To register protobuf schemas via REST, invoke a POST or PUT in the ___protobuf_metadata cache as in the following example:

curl -u user:password -X POST --data-binary @./schema.proto

When writing JSON documents, a special field _type must be present in the document to identity the Protobuf Message that corresponds to the document.


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


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

1.4. Cross-Origin Resource Sharing (CORS) Requests

The Data Grid REST connector supports CORS, including preflight and rules based on the request origin.

The following shows an example REST connector configuration with CORS rules:

<rest-connector name="rest1" socket-binding="rest" cache-container="default">
      <cors-rule name="restrict host1"
      <cors-rule name="allow ALL"

Data Grid evaluates CORS rules sequentially based on the "Origin" header set by the browser.

In the preceding example, if the origin is either "http://host1" or "https://host1", then the rule "restrict host1" applies. If the origin is different, then the next rule is tested.

Because the "allow ALL" rule permits all origins, any script that has an origin other than "http://host1" or "https://host1" can perform the allowed methods and use the supplied headers.

For information about configuring CORS rules, see the Data Grid Server Configuration Schema.

1.4.1. Allowing all CORS permissions for some origins

The VM property can be used when starting the server to allow all permissions to one or more origins. Example:


All origins specified using this method will take precedence over the configured rules.