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:
- Perform an HTTP/1.1 upgrade.
- Negotiate the communication protocol using a TLS/ALPN extension.
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:
<distributed-cache>
<encoding>
<key media-type="application/x-java-object"/>
<value media-type="application/xml; charset=UTF-8"/>
</encoding>
</distributed-cache>
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=`
Headers:
Key-Content-Type: application/octet-stream
- Specifying a byte[] Key as a hexadecimal string:
API call:
GET /my-cache/0x01CA03042F
Headers:
Key-Content-Type: application/octet-stream; encoding=hex
- Specifying a double Key:
API call:
POST /my-cache/3.141456
Headers:
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=Bytesequivalent toapplication/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 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.
Person.proto
message Person {
required string name = 1;
required int32 age = 2;
}
Person.json
{
"_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-rules>
<cors-rule name="restrict host1"
allow-credentials="false">
<allowed-origins>http://host1,https://host1</allowed-origins>
<allowed-methods>GET</allowed-methods>
</cors-rule>
<cors-rule name="allow ALL"
allow-credentials="true"
max-age-seconds="2000">
<allowed-origins>*</allowed-origins>
<allowed-methods>GET,OPTIONS,POST,PUT,DELETE</allowed-methods>
<allowed-headers>Key-Content-Type</allowed-headers>
</cors-rule>
</cors-rules>
</rest-connector>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 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
All origins specified using this method will take precedence over the configured rules.
