Chapter 1. Data Grid REST Endpoint

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:

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

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.

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

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.

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.

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.

API call:

`PUT /my-cache/AQIDBDM=`

`PUT /my-cache/AQIDBDM=`

Headers:

Key-Content-Type: application/octet-stream

API call:

GET /my-cache/0x01CA03042F

Headers:

Key-Content-Type: application/octet-stream; encoding=hex

Key-Content-Type: application/octet-stream; encoding=hex

API call:

POST /my-cache/3.141456

Headers:

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

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

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

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 http://127.0.0.1:11222/rest/v2/caches/___protobuf_metadata/schema.proto

curl -u user:password -X POST --data-binary @./schema.proto http://127.0.0.1:11222/rest/v2/caches/___protobuf_metadata/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;
}

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

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

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

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

./bin/server.sh -Dinfinispan.server.rest.cors-allow=http://192.168.1.78:11222,http://host.mydomain.com

./bin/server.sh -Dinfinispan.server.rest.cors-allow=http://192.168.1.78:11222,http://host.mydomain.com

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