Chapter 1. Data Grid REST Endpoint
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. Reference Creating Data Grid users Configuring Endpoint Authentication Mechanisms 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 . 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: 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 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: Headers: Key-Content-Type: application/octet-stream Specifying a byte[] Key as a hexadecimal string: API call: GET /my-cache/0x01CA03042F Headers: Specifying a double Key: API call: POST /my-cache/3.141456 Headers: 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: 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 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: All origins specified using this method will take precedence over the configured rules.
<distributed-cache> <encoding> <key media-type="application/x-java-object"/> <value media-type="application/xml; charset=UTF-8"/> </encoding> </distributed-cache> Accept: text/plain;q=0.7, application/json;q=0.8, */*;q=0.6 `PUT /my-cache/AQIDBDM=` Key-Content-Type: application/octet-stream; encoding=hex Key-Content-Type: application/x-java-object;type=java.lang.Double curl -u user:password -X POST --data-binary @./schema.proto http://127.0.0.1:11222/rest/v2/caches/___protobuf_metadata/schema.proto message Person { required string name = 1; required int32 age = 2; } { "_type": "Person", "name": "user1", "age": 32 } <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> ./bin/server.sh -Dinfinispan.server.rest.cors-allow=http://192.168.1.78:11222,http://host.mydomain.com