Table Of Contents Next >> [Ch. 5: Compute Grid] Prev << [Ch. 4.13: Marshalling]

REST API

In this chapter

• 4.14.1 Overview
• 4.14.2 Cache Commands
• 4.14.3 Topology Commands
• 4.14.4 Task Execution Commands
• 4.14.5 REST Authentication

GridGain REST api supports external connectivity to GridGain via REST over HTTP. It comes in handy whenever GridGain Java API is not available directly, but it is still needed to execute GridGain tasks or retrieve cached data. For example, you can conveniently use GridGain REST API over HTTP from other non-JVM languages, such as Ruby, or Python or any other language, whenever local instance of GridGain is not available.

4.14.1 Overview

The most common way to utilize GridGain REST API is to use it over HTTP. Other protocols, like binary, are currently in works as well.
All REST HTTP commands have the following format:

http://localhost:8080/gridgain?cmd=exe&...

where cmd is the name of the command followed by other command parameters. Every command may have different parameters, some of which may be mandatory and some optional. The commands parameters may be passed either via HTTP GET or POST, whichever one is preferred.

All commands return response in JSON format with following fields (note that some commands may return additional fields as well):

4.14.2 Cache Commands

All cache commands in GridGain have one additional field in responses - affinityNodeId which tells the node ID of the primary node responsible for caching requested data. Users can use this ID to send future requests for the same data to the primary affinity node for better performance. Otherwise, whenever a request for data arrive on some node, that node will have to figure out the primary affinity node responsible for caching requested data and then send the request there. This will involve an extra network round trip which could have been avoided if the request came to the primary node directly.

The following list of commands are available to access GridGain cache.

GET

GET command is used get a value stored in cache. It is analogous to invoking GridCacheProjection.get(someKey) ^Javadoc method. GET command supports the following parameters:

Example Request

http://localhost:8080/gridgain?cmd=get&cacheName=mycache&key=mykey

Example Response

{"affinityNodeId":"d2ee8ea4-a2f0-4f41-9edd-ea25d68de6f8","error":"","response":"some-value","success":true}

PUT

PUT command is used to store a value in cache. It is analogous to invoking GridCacheProjection.putx(someKey, someValue) ^Javadoc method. PUT command supports the following parameters:

Example Request

http://localhost:8080/gridgain?cmd=put&cacheName=mycache&key=mykey&val=myval

Example Response

{"affinityNodeId":"d2ee8ea4-a2f0-4f41-9edd-ea25d68de6f8","error":"","response":true,"success":true}

REMOVE

REMOVE command is used remove a mapping stored in cache. It is analogous to invoking GridCacheProjection.removex(someKey) ^Javadoc method. REMOVE command supports the following parameters:

Example Request

http://localhost:8080/gridgain?cmd=rmv&cacheName=mycache&key=mykey

Example Response

{"affinityNodeId":"d2ee8ea4-a2f0-4f41-9edd-ea25d68de6f8","error":"","response":true,"success":true}

REPLACE

REPLACE command is used to replace a value in cache only if there is already some existing mapping for the specified key. It is analogous to invoking GridCacheProjection.replacex(someKey, someValue) ^Javadoc method. REPLACE command supports the following parameters:

Example Request

http://1localhost:8080/gridgain?cmd=rep&cacheName=mycache&key=mykey&val=myval

Example Response

{"affinityNodeId":"d2ee8ea4-a2f0-4f41-9edd-ea25d68de6f8","error":"","response":false,"success":true}

CAS

CAS command stands for compare-and-set and is used to replace a value in cache only if it matches the provided value. Based on the values passed in, it has different behavior.

• If both, val1 and val2 are null or empty, then this command is analogous to REMOVE command.
• If val1 is not null or empty, but val2 is, then this command will store a value in cache only if there no existing mapping for the provided key. It is analogous to invoking GridCacheProjection.putxIfAbsent(someKey, someValue) ^Javadoc method.
• If val1 is null or empty, but val2 is not, then this command will remove a mapping for provided key only if current value is equal to val2. It is analogous to invoking GridCacheProjection.remove(someKey, someValue) ^Javadoc method.
• If both, val1 and val2 are not null or empty, then this command will replace a mapping for provided key only if current value is equal to val2. It is analogous to invoking GridCacheProjection.replace(someKey, oldValue, newValue) ^Javadoc method.

CAS command supports the following parameters:

Example Request

http://localhost:8080/gridgain?cmd=cas&cacheName=mycache&key=mykey&val1=oldVal&val2=newVal

Example Response

{"affinityNodeId":"d2ee8ea4-a2f0-4f41-9edd-ea25d68de6f8","error":"","response":false,"success":true}

AFFINITY

AFFINITY command is used to retrieve primary affinity node responsible for storing cache key. It is analogous to invoking GridCacheProjection.mapKeyToNode(someKey) ^Javadoc method. AFFINITY command supports the following parameters:

Example Request

http://localhost:8080/gridgain?cmd=aff&cacheName=mycache&key=mykey

Example Response

{"affinityNodeId":"d2ee8ea4-a2f0-4f41-9edd-ea25d68de6f8","error":"","response":true,"success":true}

METRICS

METRICS command is used to retrieve cache metrics or cache entry metrics.
METRICS command supports the following parameters:

Example Request

http://localhost:8080/gridgain?cmd=cache&cacheName=mycache

Example Response

{"affinityNodeId":"","error":"","response":{"createTime":1298362596532,"hits":1,"misses":1,"readTime":1298363347487,"reads":2,"writeTime":1298362597375,"writes":7},"success":true}

4.14.3 Topology Commands

Topology commands are used to retrieved various grid topology information from GridGain. The following commands are available to access GridGain topology:

TOPOLOGY

TOPOLOGY command is used to retrieve list of available GridGain nodes in grid topology.
TOPOLOGY command supports the following parameters:

Example Request

http://localhost:8080/gridgain?cmd=top&mtr=false&attr=false

Example Response

{"error":"","response":[{"attributes":null,"externalAddresses":[],"internalAddresses":["localhost"],"metrics":null,"nodeId":"4ffa1248-0d4f-4e4a-bf79-e8b586b0dc31"}],"success":true}

NODE

NODE command is used to retrieve information about a single GridGain node based on either node ID or any of node's available IP addresses.
NODE command supports the following parameters:

Example Request

http://localhost:8080/gridgain?cmd=node&ip=1.2.3.4&id=4ffa1248-0d4f-4e4a-bf79-e8b586b0dc31

Example Response

{"error":"","response":{"attributes":null,"externalAddresses":[],"internalAddresses":["1.2.3.4"],"metrics":null,"nodeId":"4ffa1248-0d4f-4e4a-bf79-e8b586b0dc31"},"success":true}

4.14.4 Task Execution Commands

Task execution commands provide a way to execute GridGain tasks over HTTP.

Task execution commands respond with the special entity having the following fields:

The following commands are available for GridGain task execution:

EXE

EXE command is used to execute GridGain task remotely with specified parameters and returns task execution result back (or task ID to query results in case of asynchronous execution).
EXE command supports the following parameters:

Example Request

http://localhost:8080/gridgain?cmd=exe&name=org.gridgain.grid.kernal.controllers.rest.TestTask2

Example Response

{"error":"","response":{"error":"","finished":true,"id":"0e731fb3-77ba-4932-b625-a2e197bc444c~16cd1450-fa4f-4bb0-8029-6048b905a5dc","result":"Task 2 result."},"success":true}

Example Request

http://localhost:8080/gridgain?cmd=exe&name=org.gridgain.grid.kernal.controllers.rest.TestTask2&timeout=1&async=true

Example Response

{"error":"","response":{"error":"","finished":false,"id":"7b3d682e-759c-4310-aaa2-ddfba54fb0b8~16cd1450-fa4f-4bb0-8029-6048b905a5dc","result":null},"success":true}

RESULT

RESULT command is used to retrieve results of GridGain task execution (initiated by EXE command).
RESULT command supports the following parameters:

Example Request

http://localhost:8080/gridgain?cmd=res&id=80ae2a49-029e-439a-bee5-8bad67381173~4186cc96-0f62-45dc-976f-979bfea08a90

Example Response

{"error":"","response":{"error":"","finished":true,"id":"80ae2a49-029e-439a-bee5-8bad67381173~4186cc96-0f62-45dc-976f-979bfea08a90","result":"Task 2 result."},"success":true}

4.14.5 REST Authentication

To control access to the REST API, you may require authentication by providing REST secret key (GridConfiguration.getRestSecretKey() ^Javadoc).
If secret key is provided, then all requests should contain authentication token.
For REST over http(s) token is sent via X-Signature header.
Token is built using the following algorithm:

1. Client makes up a string out of timestamp (in milliseconds) and secret key separated by semicolon - timestamp:secretKey;
2. Client calculates SHA-1 hash of the string;
3. Finally makes up a token out of timestamp value and BASE64 encoded hash calculated during the previous step - timstamp:hash_base64.

Protocol implementations split token to fetch timestamp and make the same operations, then compare the result hash with provided one. If results are equal request is authenticated.

Enhanced Security For more security it is recommended to access REST API via https instead of http.

Example