REST API

GridGain provides an HTTP REST client that gives you the ability to communicate with the grid over HTTP and HTTPS protocols using the REST approach. REST APIs can be used to perform different operations like read/write from/to cache, execute tasks, get various metrics, and more.

Internally, GridGain uses Jetty to provide HTTP server features. See Configuration section below for details on how to configure jetty.

Getting Started

To enable HTTP connectivity, make sure that the ignite-rest-http module is enabled. If you use the binary distribution, copy the ignite-rest-http module from IGNITE_HOME/libs/optional/ to the IGNITE_HOME/libs folder. See Enabling modules for details.

Explicit configuration is not required; the connector starts up automatically and listens on port 8080. You can check if it works with curl:

curl 'http://localhost:8080/ignite?cmd=version'

Request parameters may be provided as either a part of URL or in a form data:

curl 'http://localhost:8080/ignite?cmd=put&cacheName=myCache' -X POST -H 'Content-Type: application/x-www-form-urlencoded' -d 'key=testKey&val=testValue'

Configuration

You can change HTTP server parameters as follows:

<bean class="org.apache.ignite.configuration.IgniteConfiguration" id="ignite.cfg">
    <property name="connectorConfiguration">
        <bean class="org.apache.ignite.configuration.ConnectorConfiguration">
            <property name="jettyPath" value="jetty.xml"/>
        </bean>
    </property>
</bean>

IgniteConfiguration cfg = new IgniteConfiguration();
cfg.setConnectorConfiguration(new ConnectorConfiguration().setJettyPath("jetty.xml"));

// This example loads configuration from a file.
// You can use a custom configuration following the instructions in jetty documentation at https://jetty.org/.
private static class JettyServerFactory implements Factory<Server> {

    private static final long serialVersionUID = 0L;

    @Override public Server create() {
        log.info(">>>>> Using custom Jetty server initialization.");

        URL cfgUrl = U.resolveIgniteUrl(JETTY_CFG_PATH);

        XmlConfiguration cfg;

        try {
            cfg = new XmlConfiguration(Resource.newResource(cfgUrl));
        }
        catch (FileNotFoundException e) {
            throw new IgniteSpiException("Failed to find configuration file: " + cfgUrl, e);
        }
        catch (SAXException e) {
            throw new IgniteSpiException("Failed to parse configuration file: " + cfgUrl, e);
        }
        catch (IOException e) {
            throw new IgniteSpiException("Failed to load configuration file: " + cfgUrl, e);
        }
        catch (Exception e) {
            throw new IgniteSpiException("Failed to start HTTP server with configuration file: " + cfgUrl, e);
        }

        try {
            return (Server)cfg.configure();
        }
        catch (Exception e) {
            throw new IgniteException("Failed to start Jetty HTTP server.", e);
        }
    }
}

public IgniteConfiguration createIgniteConfiguration() {
    IgniteConfiguration igniteConfig = new IgniteConfiguration();

    ConnectorConfiguration connectorConfig = new ConnectorConfiguration();
    connectorConfig.setJettyServerFactory(new JettyServerFactory());

    igniteConfig.setConnectorConfiguration(connectorConfig);

    return igniteConfig;
}

This API is not presently available for C++. You can use XML configuration.

The following table describes the properties of ConnectorConfiguration that are related to the http server:

Parameter Name Description Optional Default Value

Parameter Name	Description	Optional	Default Value
`setSecretKey(String)`	Defines secret key used for client authentication. When provided, client request must contain `HTTP header X-Signature` with the string "[1]:[2]", where [1] is timestamp in milliseconds and [2] is the Base64 encoded SHA1 hash of the secret key.	Yes	`null`
`setPortRange(int)`	Port range for Jetty server. If the port provided in Jetty configuration or `IGNITE_JETTY_PORT` system property is already in use, Ignite iteratively increments port by 1 and tries to bind once again until provided port range is exceeded.	Yes	`100`
`setJettyPath(String)`	Path to Jetty configuration file. Should be either absolute or relative to `IGNITE_HOME`. If the path is not set, GridGain starts a Jetty server with a simple HTTP connector. This connector uses `IGNITE_JETTY_HOST` and `IGNITE_JETTY_PORT` system properties as `host` and `port` respectively. If `IGNITE_JETTY_HOST` is not provided, `localhost` is used as default. If `IGNITE_JETTY_PORT` is not provided, port `8080` is used.	Yes	`null`
`setMessageInterceptor(ConnectorMessageInterceptor)`	The interceptor provides the ability to transform all objects exchanged via REST protocol. For example, if you use custom serialisation on client you can write an interceptor to transform binary representations received from the client to Java objects and later access them from Java code directly.	Yes	`null`

setSecretKey(String)

Defines secret key used for client authentication. When provided, client request must contain HTTP header X-Signature with the string "[1]:[2]", where [1] is timestamp in milliseconds and [2] is the Base64 encoded SHA1 hash of the secret key.

Yes

null

setPortRange(int)

Port range for Jetty server. If the port provided in Jetty configuration or IGNITE_JETTY_PORT system property is already in use, Ignite iteratively increments port by 1 and tries to bind once again until provided port range is exceeded.

Yes

100

setJettyPath(String)

Path to Jetty configuration file. Should be either absolute or relative to IGNITE_HOME. If the path is not set, GridGain starts a Jetty server with a simple HTTP connector. This connector uses IGNITE_JETTY_HOST and IGNITE_JETTY_PORT system properties as host and port respectively. If IGNITE_JETTY_HOST is not provided, localhost is used as default. If IGNITE_JETTY_PORT is not provided, port 8080 is used.

Yes

null

setMessageInterceptor(ConnectorMessageInterceptor)

The interceptor provides the ability to transform all objects exchanged via REST protocol. For example, if you use custom serialisation on client you can write an interceptor to transform binary representations received from the client to Java objects and later access them from Java code directly.

Yes

null

Example Jetty XML Configuration

Path to this configuration should be set to ConnectorConfiguration.setJettyPath(String) as explained above.

<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd">
<Configure id="Server" class="org.eclipse.jetty.server.Server">
    <Arg name="threadpool">
        <!-- Default queued blocking thread pool -->
        <New class="org.eclipse.jetty.util.thread.QueuedThreadPool">
            <Set name="minThreads">20</Set>
            <Set name="maxThreads">200</Set>
        </New>
    </Arg>
    <New id="httpCfg" class="org.eclipse.jetty.server.HttpConfiguration">
        <Set name="secureScheme">https</Set>
        <Set name="securePort">8443</Set>
        <Set name="sendServerVersion">true</Set>
        <Set name="sendDateHeader">true</Set>
    </New>
    <Call name="addConnector">
        <Arg>
            <New class="org.eclipse.jetty.server.ServerConnector">
                <Arg name="server"><Ref refid="Server"/></Arg>
                <Arg name="factories">
                    <Array type="org.eclipse.jetty.server.ConnectionFactory">
                        <Item>
                            <New class="org.eclipse.jetty.server.HttpConnectionFactory">
                                <Ref refid="httpCfg"/>
                            </New>
                        </Item>
                    </Array>
                </Arg>
                <Set name="host">
                  <SystemProperty name="IGNITE_JETTY_HOST" default="localhost"/>
                </Set>
                <Set name="port">
                  <SystemProperty name="IGNITE_JETTY_PORT" default="8080"/>
                </Set>
                <Set name="idleTimeout">30000</Set>
                <Set name="reuseAddress">true</Set>
            </New>
        </Arg>
    </Call>
    <Set name="handler">
        <New id="Handlers" class="org.eclipse.jetty.server.handler.HandlerCollection">
            <Set name="handlers">
                <Array type="org.eclipse.jetty.server.Handler">
                    <Item>
                        <New id="Contexts" class="org.eclipse.jetty.server.handler.ContextHandlerCollection"/>
                    </Item>
                </Array>
            </Set>
        </New>
    </Set>
    <Set name="stopAtShutdown">false</Set>
</Configure>

Security

When authentication is configured in the cluster, all applications that use REST API request authentication by providing security credentials. The authentication request returns a session token that can be used with any command within that session.

There are two ways to request authorization:

Use the authenticate command with ignite.login=[user]&ignite.password=[password] parameters.

https://[host]:[port]/ignite?cmd=authenticate&ignite.login=[user]&ignite.password=[password]

Use any REST command with ignite.login=[user]&ignite.password=[password] parameters in the path of your connection string. In our example below, we use the version command:
http://[host]:[port]/ignite?cmd=version&ignite.login=[user]&ignite.password=[password]
In both examples above, replace [host], [port], [user], and [password] with actual values.

Executing any one of the above strings in a browser returns a response with a session token which looks like this:

{"successStatus":0,"error":null,"sessionToken":"EF6013FF590348CE91DEAE9870183BEF","response":true}

Once you obtain the session token, use the sessionToken parameter with your connection string as shown in the example below:

http://[host]:[port]/ignite?cmd=top&sessionToken=[sessionToken]

In the above connection string, replace [host], [port], and [sessionToken] with actual values.

Either user credentials or a session token is required when authentication is enabled on the server. Failure to provide either a sessionToken or user & password parameters in the REST connection string results in an error:

{
    "successStatus":2,
    "sessionToken":null,
    "error":"Failed to handle request - session token not found or invalid",
    "response":null
}

Session Token Expiration

A session token is valid only for 30 seconds. Using an expired session token results in an error, like the one below:

{
    "successStatus":1,
    "error":"Failed to handle request - unknown session token (maybe expired session) [sesTok=12FFFD4827D149068E9FFF59700E5FDA]",
    "sessionToken":null,
    "response":null
}

To set a custom expire time, set the system variable: IGNITE_REST_SESSION_TIMEOUT (in seconds).

-DIGNITE_REST_SESSION_TIMEOUT=3600

Data Types

The REST API also provides support for Java built-in types for put/get operations via keyType and valueType optional parameters. Note that unless one of the below mentioned types are explicitly specified, the REST protocol exchanges the key-value data in String format. This means that the data is stored and retrieved to/from the cluster as a String.

REST KeyType/ValueType Corresponding Java Type

REST KeyType/ValueType	Corresponding Java Type
`boolean`	`java.lang.Boolean`
`byte`	`java.lang.Byte`
`short`	`java.lang.Short`
`integer`	`java.lang.Integer`
`long`	`java.lang.Long`
`float`	`java.lang.Float`
`double`	`java.lang.Double`
`date`	`java.sql.Date` The date value should be in the format as specified in the `valueOf(String)` method in the Java documentation Example: 2018-01-01
`time`	`java.sql.Time` The time value should be in the format as specified in the `valueOf(String)` method in the Java documentation Example: 01:01:01
`timestamp`	`java.sql.Timestamp` The timestamp value should be in the format as specified in the `valueOf(String)` method in the Java documentation Example: 2018-02-18%2001:01:01
`uuid`	`java.util.UUID`
`IgniteUuid`	`org.apache.ignite.lang.IgniteUuid`

boolean

java.lang.Boolean

byte

java.lang.Byte

short

java.lang.Short

integer

java.lang.Integer

long

java.lang.Long

float

java.lang.Float

double

java.lang.Double

date

java.sql.Date

The date value should be in the format as specified in the valueOf(String) method in the Java documentation

Example: 2018-01-01

time

java.sql.Time

The time value should be in the format as specified in the valueOf(String) method in the Java documentation

Example: 01:01:01

timestamp

java.sql.Timestamp

The timestamp value should be in the format as specified in the valueOf(String) method in the Java documentation

Example: 2018-02-18%2001:01:01

uuid

java.util.UUID

IgniteUuid

org.apache.ignite.lang.IgniteUuid

The following example shows a put command with keyType=int and valueType=date:

http://[host]:[port]/ignite?cmd=put&key=1&val=2018-01-01&cacheName=myCache&keyType=int&valueType=date

Similarly, the get command with keyType=int and valueType=date would be:

http://[host]:[port]/ignite?cmd=get&key=1&cacheName=myCache&keyType=int&valueType=date

Custom Data Types

The GridGain REST API does not recognize custom data types out-of-the-box. However, you can handle custom data types with the use of ConnectorMessageInterceptor - a function that intercepts an API call with a custom data type, converts it to a user’s class. After that, GridGain can work with an instance of that class as with any other object.

For example:

IgniteConfiguration igniteConfiguration = new IgniteConfiguration();

ConnectorConfiguration connectorConfiguration = new ConnectorConfiguration();

connectorConfiguration.setMessageInterceptor(new ConnectorMessageInterceptor() {
    @Override
    public Object onReceive(Object obj) {
        if (obj instanceof String) {
            // Converting the JSON representation to a user-defined object using the Jackson library.
            return JSON_MAPPER.readValue((String) obj, CustomObject.class);
        }

        return obj;
    }

    @Override
    public Object onSend(Object obj) {
        if (obj instanceof CustomObject) {
            return JSON_MAPPER.writeValueAsString(obj);
        }

        return obj;
    }
});

Binary Objects in Query Results

By default, query commands deserialize cache entries into their Java classes on the server node. If a class is missing from the server classpath, the query fails. Use the keepBinary=true parameter to keep entries in binary form. GridGain serializes each binary object to JSON directly from its type metadata. The server never loads the class.

The parameter is supported by SQL Query Execute, SQL Fields Query Execute, and SQL Scan Query Execute. The setting applies to the whole query, so later pages fetched with SQL Query Fetch stay in binary form.

A binary object is rendered as a flat JSON object with one property per field. Field order follows the type metadata. Nested binary objects are rendered the same way.

The output matches what the same query returns without keepBinary. In a fields query, a binary value appears as a JSON object in its column position.

Returned Value

The HTTP REST request returns a JSON object which has a similar structure for each command:

Field Type Description Example

Field	Type	Description	Example
`affinityNodeId`	`string`	Affinity node ID.	`2bd7b049-3fa0-4c44-9a6d-b5c7a597ce37`
`error`	`string`	This field contains description of error if server could not handle the request.	Specifically for each command.
`sessionToken`	`string`	When authentication is enabled on the server, this field contains a session token that can be used with any command within that session. If authentication is off, this field contains `null`. When authentication is enabled - `EF6013FF590348CE91DEAE9870183BEF`	Otherwise, `null`.
`response`	`jsonObject`	This field contains the result of the command.	Specifically for each command.
`successStatus`	`integer`	Exit status code. It might have the following values: `success = 0` `failed = 1` `authorization failed = 2` `security check failed = 3`	`0`

affinityNodeId

string

Affinity node ID.

2bd7b049-3fa0-4c44-9a6d-b5c7a597ce37

error

string

This field contains description of error if server could not handle the request.

Specifically for each command.

sessionToken

string

When authentication is enabled on the server, this field contains a session token that can be used with any command within that session. If authentication is off, this field contains null. When authentication is enabled - EF6013FF590348CE91DEAE9870183BEF

Otherwise, null.

response

jsonObject

This field contains the result of the command.

Specifically for each command.

successStatus

integer

Exit status code. It might have the following values:

success = 0

failed = 1

authorization failed = 2

security check failed = 3

0

REST API Reference

Version

Returns the GridGain version.

Request:

http://host:port/ignite?cmd=version

Response:

{
  "error": "",
  "response": "1.0.0",
  "successStatus": 0
}

Activate

Activates the cluster.

Request:

http://host:port/ignite?cmd=activate

Response:

{
  "successStatus":0,
  "error":null,
  "sessionToken":null,
  "response":"activate started"
}

Deactivate

Starts the deactivation process for a persistence-enabled cluster.

Request:

http://host:port/ignite?cmd=deactivate

Response:

{
  "successStatus":0,
  "error":null,
  "sessionToken":null,
  "response":"deactivate started"
}

Current State

Returns the current state (active/inactive) of the cluster.

Request:

http://host:port/ignite?cmd=currentstate

Response:

Returns true if the cluster is active. Returns false if the cluster in inactive.

{
  "successStatus":0,
  "error":null,
  "sessionToken":null,
  "response":true
}

Increment

Adds and gets current value of given atomic long.

Request:

http://host:port/ignite?cmd=incr&key={incrKey}&init={initialValue}&delta={delta}

Parameter Type Optional Description Example

Parameter	Type	Optional	Description	Example
`key`	string		The name of atomic long.	counter
`init`	long	Yes	Initial value.	15
`delta`	long		Number to be added.	42

key

string

The name of atomic long.

counter

init

long

Yes

Initial value.

delta

long

Number to be added.

Response:

The response contains the value after the operation.

{
  "affinityNodeId": "e05839d5-6648-43e7-a23b-78d7db9390d5",
  "error": "",
  "response": 42,
  "successStatus": 0
}

Decrement

Subtracts and gets current value of given atomic long.

Request:

http://host:port/ignite?cmd=decr&key={key}&init={init_value}&delta={delta}

Parameter Type Optional Description Example

Parameter	Type	Optional	Description	Example
`key`	string		The name of atomic long.	counter
`init`	long	Yes	Initial value.	`15`
`delta`	long		Number to be subtracted.	`42`

key

string

The name of atomic long.

counter

init

long

Yes

Initial value.

15

delta

long

Number to be subtracted.

42

Response:

The response contains the value after the operation.

{
  "affinityNodeId": "e05839d5-6648-43e7-a23b-78d7db9390d5",
  "error": "",
  "response": -42,
  "successStatus": 0
}

Cache Metrics

Shows metrics for a cache.

Request:

http://host:port/ignite?cmd=cache&cacheName={cacheName}&destId={nodeId}

Parameter Type Optional Description Example

Parameter	Type	Optional	Description	Example
`cacheName`	string	Yes	Cache name.	partitionedCache
`destId`	string	Yes	Node ID for which the metrics are to be returned.	8daab5ea-af83-4d91-99b6-77ed2ca06647

cacheName

string

Yes

Cache name.

partitionedCache

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response:

{
  "affinityNodeId": "",
  "error": "",
  "response": {
    "hits": 0,
    "misses": 0,
    "reads": 0,
    "writes": 2
  },
  "successStatus": 0
}

Field Type Description Example

Field	Type	Description	Example
`response`	jsonObject	The JSON object contains cache metrics such as create time, count reads and etc.	`{ "createTime": 1415179251551, "hits": 0, "misses": 0, "readTime":1415179251551, "reads": 0,"writeTime": 1415179252198, "writes": 2 }`

response

jsonObject

The JSON object contains cache metrics such as create time, count reads and etc.

{ "createTime": 1415179251551, "hits": 0, "misses": 0, "readTime":1415179251551, "reads": 0,"writeTime": 1415179252198, "writes": 2 }

Cache Size

Gets the number of all entries cached across all nodes.

Request:

http://host:port/ignite?cmd=size&cacheName={cacheName}

Parameter Type Optional Description Example

Parameter	Type	Optional	Description	Example
`cacheName`	string	Yes	Cache name.	partitionedCache

cacheName

string

Yes

Cache name.

partitionedCache

Response:

{
  "affinityNodeId": "",
  "error": "",
  "response": 1,
  "successStatus": 0
}

Field Type Description Example

Field	Type	Description	Example
`response`	number	Number of all entries cached across all nodes.	5

response

number

Number of all entries cached across all nodes.

Cache Metadata

Gets metadata for a cache.

Request:

http://host:port/ignite?cmd=metadata&cacheName={cacheName}

Parameter Type Optional Description Example

Parameter	Type	Optional	Description	Example
`cacheName`	String	Yes	Cache name.	partitionedCache

cacheName

String

Yes

Cache name.

partitionedCache

Response:

{
  "error": "",
  "response": {
    "cacheName": "partitionedCache",
    "types": [
      "Person"
    ],
    "keyClasses": {
      "Person": "java.lang.Integer"
    },
    "valClasses": {
      "Person": "org.apache.ignite.Person"
    },
    "fields": {
      "Person": {
        "_KEY": "java.lang.Integer",
        "_VAL": "org.apache.ignite.Person",
        "ID": "java.lang.Integer",
        "FIRSTNAME": "java.lang.String",
        "LASTNAME": "java.lang.String",
        "SALARY": "double"
      }
    },
    "indexes": {
      "Person": [
        {
          "name": "ID_IDX",
          "fields": [
            "id"
          ],
          "descendings": [],
          "unique": false
        },
        {
          "name": "SALARY_IDX",
          "fields": [
            "salary"
          ],
          "descendings": [],
          "unique": false
        }
      ]
    }
  },
  "sessionToken": "",
  "successStatus": 0
}

Compare-And-Swap

Stores a given key-value pair in a cache only if the previous value is equal to the expected value passed in.

Request:

https://[host]:[port]/ignite?cmd=authenticate&ignite.login=[user]&ignite.password=[password]

Parameter Type Optional Description Example

Parameter	Type	Optional	Description	Example
`cacheName`	string	Yes	Cache name.	partitionedCache
`key`	string		Key to store in cache.	name
`val`	string		Value associated with the given key.	Jack
`val2`	string		Expected value.	Bob
`destId`	string	Yes	Node ID for which the metrics are to be returned.	8daab5ea-af83-4d91-99b6-77ed2ca06647

cacheName

string

Yes

Cache name.

partitionedCache

key

string

Key to store in cache.

name

val

string

Value associated with the given key.

Jack

val2

string

Expected value.

Bob

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response:

The response returns true if the value was replaced, false otherwise.

{
  "affinityNodeId": "1bcbac4b-3517-43ee-98d0-874b103ecf30",
  "error": "",
  "response": true,
  "successStatus": 0
}

Append

Appends a line for value which is associated with key.

Request:

http://host:port/ignite?cmd=append&key={appendKey}&val={_suffix}&cacheName={cacheName}&destId={nodeId}

Parameter Type Optional Description Example

Parameter	Type	Optional	Description	Example
`cacheName`	string	Yes	Cache name.	partitionedCache
`key`	string		Key to store in cache.	name
`val`	string		Value to be appended to the current value.	Jack
`destId`	string	Yes	Node ID for which the metrics are to be returned.	8daab5ea-af83-4d91-99b6-77ed2ca06647

cacheName

string

Yes

Cache name.

partitionedCache

key

string

Key to store in cache.

name

val

string

Value to be appended to the current value.

Jack

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response:

{
  "affinityNodeId": "1bcbac4b-3517-43ee-98d0-874b103ecf30",
  "error": "",
  "response": true,
  "successStatus": 0
}

Field Type Description Example

Field	Type	Description	Example
`response`	boolean	`true` if replace happened, `false` otherwise.	true

response

boolean

true if replace happened, false otherwise.

true

Prepend

Adds prefix to the value that is associated with a given key.

Request:

http://host:port/ignite?cmd=prepend&key={key}&val={value}&cacheName={cacheName}&destId={nodeId}

Parameter Type Optional Description Example

Parameter	Type	Optional	Description	Example
`cacheName`	string	Yes	Cache name.	myCache
`key`	string		Key to store in cache.	name
`val`	string		The string to be prepended to the current value.	Name_
`destId`	string	Yes	Node ID for which the metrics are to be returned.	8daab5ea-af83-4d91-99b6-77ed2ca06647

cacheName

string

Yes

Cache name.

myCache

key

string

Key to store in cache.

name

val

string

The string to be prepended to the current value.

Name_

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response:

{
  "affinityNodeId": "1bcbac4b-3517-43ee-98d0-874b103ecf30",
  "error": "",
  "response": true,
  "successStatus": 0
}

Field Type Description Example

Field	Type	Description	Example
`response`	boolean	`true` if replace happened, `false` otherwise.	true

response

boolean

true if replace happened, false otherwise.

true

Replace

Stores a given key-value pair in a cache if the cache already contains the key.

Request:

http://host:port/ignite?cmd=rep&key=repKey&val=newValue&cacheName={cacheName}&destId={nodeId}

Parameter Type Optional Description Example

Parameter	Type	Optional	Description	Example
`cacheName`	string	Yes	Cache name.	partitionedCache
`key`	string		Key to store in cache.	name
`val`	string		Value associated with the given key.	Jack
`destId`	string	Yes	Node ID for which the metrics are to be returned.	8daab5ea-af83-4d91-99b6-77ed2ca06647
`exp`	long	Yes	Expiration time in milliseconds for the entry. When the parameter is set, the operation is executed with ModifiedExpiryPolicy.	60000

cacheName

string

Yes

Cache name.

partitionedCache

key

string

Key to store in cache.

name

val

string

Value associated with the given key.

Jack

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

exp

long

Yes

Expiration time in milliseconds for the entry. When the parameter is set, the operation is executed with ModifiedExpiryPolicy.

60000

Response:

The response contains true if the value was replaced, false otherwise.

{
  "affinityNodeId": "1bcbac4b-3517-43ee-98d0-874b103ecf30",
  "error": "",
  "response": true,
  "successStatus": 0
}

Get

Retrieves the value mapped to a specified key from a cache.

Request:

http://host:port/ignite?cmd=get&key={getKey}&cacheName={cacheName}&destId={nodeId}

Parameter Type Optional Description Example

Parameter	Type	Optional	Description	Example
`cacheName`	string	Yes	Cache name.	partitionedCache
`key`	string		Key whose associated value is to be returned.	testKey
`keyType`	Java built-in type	Yes	See Data Types for more details.
`destId`	string	Yes	Node ID for which the metrics are to be returned.	8daab5ea-af83-4d91-99b6-77ed2ca06647

cacheName

string

Yes

Cache name.

partitionedCache

key

string

Key whose associated value is to be returned.

testKey

keyType

Java built-in type

Yes

See Data Types for more details.

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Get All

Retrieves values mapped to the specified keys from a given cache.

Request:

http://host:port/ignite?cmd=getall&k1={getKey1}&k2={getKey2}&k3={getKey3}&cacheName={cacheName}&destId={nodeId}

Parameter Type Optional Description Example

Parameter	Type	Optional	Description	Example
`cacheName`	string	Yes	Cache name.	partitionedCache
`k1…kN`	string		Keys whose associated values are to be returned.	key1, key2, …, keyN
`destId`	string	Yes	Node ID for which the metrics are to be returned.	8daab5ea-af83-4d91-99b6-77ed2ca06647

cacheName

string

Yes

Cache name.

partitionedCache

k1…kN

string

Keys whose associated values are to be returned.

key1, key2, …, keyN

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response:

{
  "affinityNodeId": "",
  "error": "",
  "response": {
    "key1": "value1",
    "key2": "value2"
  },
  "successStatus": 0
}

Get and Remove

Removes the given key mapping from cache and returns the previous value.

Request:

http://host:port/ignite?cmd=getrmv&cacheName={cacheName}&destId={nodeId}&key={key}

Parameter Type Optional Description Example

Parameter	Type	Optional	Description	Example
`cacheName`	string	Yes	Cache name.	partitionedCache
`key`	string		Key whose mapping is to be removed from the cache.	name
`destId`	string	Yes	Node ID for which the metrics are to be returned.	8daab5ea-af83-4d91-99b6-77ed2ca06647

cacheName

string

Yes

Cache name.

partitionedCache

key

string

Key whose mapping is to be removed from the cache.

name

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response:

{
  "affinityNodeId": "1bcbac4b-3517-43ee-98d0-874b103ecf30",
  "error": "",
  "response": value,
  "successStatus": 0
}

Field Type Description Example

Field	Type	Description	Example
`response`	jsonObject	Value for the key.	`{"name": "bob"}`

response

jsonObject

Value for the key.

{"name": "bob"}

Get and Put

Stores a given key-value pair in a cache and returns the existing value if there is one.

Request:

http://host:port/ignite?cmd=getput&key=getKey&val=newVal&cacheName={cacheName}

Parameter Type Optional Description Example

Parameter	Type	Optional	Description	Example
`cacheName`	string	Yes	Cache name.	partitionedCache
`key`	string		Key to be associated with value.	name
`val`	string		Value to be associated with key.	Jack
`destId`	string	Yes	Node ID for which the metrics are to be returned.	8daab5ea-af83-4d91-99b6-77ed2ca06647

cacheName

string

Yes

Cache name.

partitionedCache

key

string

Key to be associated with value.

name

val

string

Value to be associated with key.

Jack

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response:

The response contains the previous value for the key.

{
  "affinityNodeId": "2bd7b049-3fa0-4c44-9a6d-b5c7a597ce37",
  "error": "",
  "response": {"name": "bob"},
  "successStatus": 0
}

Get and Put If Absent

Stores given key-value pair in cache only if cache had no previous mapping for it. If cache previously contained value for the given key, then this value is returned.

Request:

http://host:port/ignite?cmd=getputifabs&key=getKey&val=newVal&cacheName={cacheName}

Parameter Type Optional Description Example

Parameter	Type	Optional	Description	Example
`cacheName`	string	Yes	Cache name.	partitionedCache
`key`	string		Key to be associated with value.	name
`val`	string		Value to be associated with key.	Jack
`destId`	string	Yes	Node ID for which the metrics are to be returned.	8daab5ea-af83-4d91-99b6-77ed2ca06647

cacheName

string

Yes

Cache name.

partitionedCache

key

string

Key to be associated with value.

name

val

string

Value to be associated with key.

Jack

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response:

{
  "affinityNodeId": "2bd7b049-3fa0-4c44-9a6d-b5c7a597ce37",
  "error": "",
  "response": "value",
  "successStatus": 0
}

Field Type Description Example

Field	Type	Description	Example
`response`	jsonObject	Previous value for the given key.	`{"name": "bob"}`

response

jsonObject

Previous value for the given key.

{"name": "bob"}

Get and Replace

Stores a given key-value pair in cache only if there is a previous mapping for it.

Request:

http://host:port/ignite?cmd=getrep&key={key}&val={val}&cacheName={cacheName}&destId={nodeId}

Parameter Type Optional Description Example

Parameter	Type	Optional	Description	Example
`cacheName`	string	Yes	Cache name.	partitionedCache
`key`	string		Key to store in cache.	name
`val`	string		Value associated with the given key.	Jack
`destId`	string	Yes	Node ID for which the metrics are to be returned.	8daab5ea-af83-4d91-99b6-77ed2ca06647

cacheName

string

Yes

Cache name.

partitionedCache

key

string

Key to store in cache.

name

val

string

Value associated with the given key.

Jack

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response:

The response contains the previous value associated with the specified key.

{
  "affinityNodeId": "1bcbac4b-3517-43ee-98d0-874b103ecf30",
  "error": "",
  "response": oldValue,
  "successStatus": 0
}

Field Type Description Example

Field	Type	Description	Example
`response`	jsonObject	The previous value associated with the specified key.	`{"name": "Bob"}`

response

jsonObject

The previous value associated with the specified key.

{"name": "Bob"}

Replace Value

Replaces the entry for a key only if currently mapped to a given value.

Request:

http://host:port/ignite?cmd=repval&key={key}&val={newValue}&val2={oldVal}&cacheName={cacheName}&destId={nodeId}

Parameter Type Optional Description Example

Parameter	Type	Optional	Description	Example
`cacheName`	string	Yes	Cache name.	partitionedCache
`key`	string		Key to store in cache.	name
`val`	string		Value associated with the given key.	Jack
`val2`	string		Value expected to be associated with the specified key.	oldValue
`destId`	string	Yes	Node ID for which the metrics are to be returned.	8daab5ea-af83-4d91-99b6-77ed2ca06647

cacheName

string

Yes

Cache name.

partitionedCache

key

string

Key to store in cache.

name

val

string

Value associated with the given key.

Jack

val2

string

Value expected to be associated with the specified key.

oldValue

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response:

{
  "affinityNodeId": "1bcbac4b-3517-43ee-98d0-874b103ecf30",
  "error": "",
  "response": true,
  "successStatus": 0
}

Field Type Description Example

Field	Type	Description	Example
`response`	boolean	`true` if replace happened, `false` otherwise.	true

response

boolean

true if replace happened, false otherwise.

true

Remove

Removes the given key mapping from cache.

Request:

http://host:port/ignite?cmd=rmv&key={rmvKey}&cacheName={cacheName}&destId={nodeId}

Parameter Type Optional Description Example

Parameter	Type	Optional	Description	Example
`cacheName`	string	Yes	Cache name.	partitionedCache
`key`	string		Key - for which the mapping is to be removed from cache.	name
`destId`	string	Yes	Node ID for which the metrics are to be returned.	8daab5ea-af83-4d91-99b6-77ed2ca06647

cacheName

string

Yes

Cache name.

partitionedCache

key

string

Key - for which the mapping is to be removed from cache.

name

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response:

{
  "affinityNodeId": "1bcbac4b-3517-43ee-98d0-874b103ecf30",
  "error": "",
  "response": true,
  "successStatus": 0
}

Field Type Description Example

Field	Type	Description	Example
`response`	boolean	`true` if replace happened, `false` otherwise.	true

response

boolean

true if replace happened, false otherwise.

true

Remove All

Removes given key mappings from a cache.

Request:

http://host:port/ignite?cmd=rmvall&k1={rmKey1}&k2={rmKey2}&k3={rmKey3}&cacheName={cacheName}&destId={nodeId}

Parameter Type Optional Description Example

Parameter	Type	Optional	Description	Example
`cacheName`	string	Yes	Cache name.	partitionedCache
`k1…kN`	string		Keys whose mappings are to be removed from the cache.	name
`destId`	string	Yes	Node ID for which the metrics are to be returned.	8daab5ea-af83-4d91-99b6-77ed2ca06647

cacheName

string

Yes

Cache name.

partitionedCache

k1…kN

string

Keys whose mappings are to be removed from the cache.

name

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response:

{
  "affinityNodeId": "1bcbac4b-3517-43ee-98d0-874b103ecf30",
  "error": "",
  "response": true,
  "successStatus": 0
}

Field Type Description Example

Field	Type	Description	Example
`response`	boolean	`true` if replace happened, `false` otherwise.	true

response

boolean

true if replace happened, false otherwise.

true

Remove Value

Removes the mapping for a key only if currently mapped to the given value.

Request:

http://host:port/ignite?cmd=rmvval&key={rmvKey}&val={rmvVal}&cacheName={cacheName}&destId={nodeId}

Parameter Type Optional Description Example

Parameter	Type	Optional	Description	Example
`cacheName`	string	Yes	Cache name.	partitionedCache
`key`	string		Key whose mapping is to be removed from the cache.	name
`val`	string		Value expected to be associated with the specified key.	oldValue
`destId`	string	Yes	Node ID for which the metrics are to be returned.	8daab5ea-af83-4d91-99b6-77ed2ca06647

cacheName

string

Yes

Cache name.

partitionedCache

key

string

Key whose mapping is to be removed from the cache.

name

val

string

Value expected to be associated with the specified key.

oldValue

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response:

{
  "affinityNodeId": "1bcbac4b-3517-43ee-98d0-874b103ecf30",
  "error": "",
  "response": true,
  "successStatus": 0
}

Field Type Description Example

Field	Type	Description	Example
`response`	boolean	`false` if there was no matching key.	true

response

boolean

false if there was no matching key.

true

Add

Stores a given key-value pair in a cache if the cache does not contain the key.

Request:

http://host:port/ignite?cmd=add&key=newKey&val=newValue&cacheName={cacheName}&destId={nodeId}

Parameter Type Optional Description Example

Parameter	Type	Optional	Description	Example
`cacheName`	string	Yes	Cache name.	partitionedCache
`key`	string		Key to be associated with the value.	name
`val`	string		Value to be associated with the key.	Jack
`destId`	string	Yes	Node ID for which the metrics are to be returned.	8daab5ea-af83-4d91-99b6-77ed2ca06647
`exp`	long	Yes	Expiration time in milliseconds for the entry. When the parameter is set, the operation is executed with ModifiedExpiryPolicy.	60000

cacheName

string

Yes

Cache name.

partitionedCache

key

string

Key to be associated with the value.

name

val

string

Value to be associated with the key.

Jack

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

exp

long

Yes

Expiration time in milliseconds for the entry. When the parameter is set, the operation is executed with ModifiedExpiryPolicy.

60000

Response:

{
  "affinityNodeId": "1bcbac4b-3517-43ee-98d0-874b103ecf30",
  "error": "",
  "response": true,
  "successStatus": 0
}

Field Type Description Example

Field	Type	Description	Example
`response`	boolean	`true` if value was stored in cache, `false` otherwise.	true

response

boolean

true if value was stored in cache, false otherwise.

true

Put

Stores a given key-value pair in a cache.

Request:

http://host:port/ignite?cmd=put&key=newKey&val=newValue&cacheName={cacheName}&destId={nodeId}

Parameter Type Optional Description Example

Parameter	Type	Optional	Description	Example
`cacheName`	string	Yes	Cache name.	partitionedCache
`key`	string		Key to be associated with values.	name
`val`	string		Value to be associated with keys.	Jack
`destId`	string	Yes	Node ID for which the metrics are to be returned.	8daab5ea-af83-4d91-99b6-77ed2ca06647
`exp`	long	Yes	Expiration time in milliseconds for the entry. When the parameter is set, the operation is executed with ModifiedExpiryPolicy.	60000

cacheName

string

Yes

Cache name.

partitionedCache

key

string

Key to be associated with values.

name

val

string

Value to be associated with keys.

Jack

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

exp

long

Yes

Expiration time in milliseconds for the entry. When the parameter is set, the operation is executed with ModifiedExpiryPolicy.

60000

Response:

{
  "affinityNodeId": "1bcbac4b-3517-43ee-98d0-874b103ecf30",
  "error": "",
  "response": true,
  "successStatus": 0
}

Field Type Description Example

Field	Type	Description	Example
`response`	boolean	`true` if value was stored in cache, `false` otherwise.	true

response

boolean

true if value was stored in cache, false otherwise.

true

Put all

Stores the given key-value pairs in cache.

Request:

http://host:port/ignite?cmd=putall&k1={putKey1}&k2={putKey2}&k3={putKey3}&v1={value1}&v2={value2}&v3={value3}&cacheName={cacheName}&destId={nodeId}

Parameter Type Optional Description Example

Parameter	Type	Optional	Description	Example
`cacheName`	string	Yes	Cache name.	partitionedCache
`k1…kN`	string		Keys to be associated with values.	name
`v1…vN`	string		Values to be associated with keys.	Jack
`destId`	string	Yes	Node ID for which the metrics are to be returned.	8daab5ea-af83-4d91-99b6-77ed2ca06647

cacheName

string

Yes

Cache name.

partitionedCache

k1…kN

string

Keys to be associated with values.

name

v1…vN

string

Values to be associated with keys.

Jack

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response:

{
  "affinityNodeId": "1bcbac4b-3517-43ee-98d0-874b103ecf30",
  "error": "",
  "response": true,
  "successStatus": 0
}

Field Type Description Example

Field	Type	Description	Example
`response`	boolean	`true` if the values were stored in cache, `false` otherwise.	true

response

boolean

true if the values were stored in cache, false otherwise.

true

Put If Absent

Stores a given key-value pair in a cache if the cache does not contain the given key.

Request:

http://host:port/ignite?cmd=putifabs&key={getKey}&val={newVal}&cacheName={cacheName}

Parameter Type Optional Description Example

Parameter	Type	Optional	Description	Example
`cacheName`	string	Yes	Cache name.	partitionedCache
`key`	string		Key to be associated with value.	name
`val`	string		Value to be associated with key.	Jack
`destId`	string	Yes	Node ID for which the metrics are to be returned.	8daab5ea-af83-4d91-99b6-77ed2ca06647
`exp`	long	Yes	Expiration time in milliseconds for the entry. When the parameter is set, the operation is executed with ModifiedExpiryPolicy.	60000

cacheName

string

Yes

Cache name.

partitionedCache

key

string

Key to be associated with value.

name

val

string

Value to be associated with key.

Jack

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

exp

long

Yes

Expiration time in milliseconds for the entry. When the parameter is set, the operation is executed with ModifiedExpiryPolicy.

60000

Response:

The response field contains true if the entry was put, false otherwise.

{
  "affinityNodeId": "2bd7b049-3fa0-4c44-9a6d-b5c7a597ce37",
  "error": "",
  "response": true,
  "successStatus": 0
}

Contains Key

Determines if cache contains an entry for the specified key.

Request:

http://host:port/ignite?cmd=conkey&key={getKey}&cacheName={cacheName}

Parameter Type Optional Description Example

Parameter	Type	Optional	Description	Example
`cacheName`	string	Yes	Cache name.	partitionedCache
`key`	string		Key whose presence in this cache is to be tested.	testKey
`destId`	string	Yes	Node ID for which the metrics are to be returned.	8daab5ea-af83-4d91-99b6-77ed2ca06647

cacheName

string

Yes

Cache name.

partitionedCache

key

string

Key whose presence in this cache is to be tested.

testKey

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response:

{
  "affinityNodeId": "2bd7b049-3fa0-4c44-9a6d-b5c7a597ce37",
  "error": "",
  "response": true,
  "successStatus": 0
}

Field Type Description Example

Field	Type	Description	Example
`response`	boolean	`true` if this map contains a mapping for the specified key.	true

response

boolean

true if this map contains a mapping for the specified key.

true

Contains keys

Determines if cache contains any entries for the specified keys.

Request:

http://host:port/ignite?cmd=conkeys&k1={getKey1}&k2={getKey2}&cacheName={cacheName}

Parameter Type Optional Description Example

Parameter	Type	Optional	Description	Example
`cacheName`	string	Yes	Cache name.	partitionedCache
`k1…kN`	string		Key whose presence in this cache is to be tested.	key1, key2, …, keyN
`destId`	string	Yes	Node ID for which the metrics are to be returned.	`8daab5ea-af83-4d91-99b6-77ed2ca06647`

cacheName

string

Yes

Cache name.

partitionedCache

k1…kN

string

Key whose presence in this cache is to be tested.

key1, key2, …, keyN

destId

string

Yes

Node ID for which the metrics are to be returned.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response:

{
  "affinityNodeId": "2bd7b049-3fa0-4c44-9a6d-b5c7a597ce37",
  "error": "",
  "response": true,
  "successStatus": 0
}

Field Type Description Example

Field	Type	Description	Example
`response`	boolean	`true` if this cache contains a mapping for the specified keys.	true

response

boolean

true if this cache contains a mapping for the specified keys.

true

Get or Create Cache

Creates a cache with the given name if it does not exist.

Request:

http://host:port/ignite?cmd=getorcreate&cacheName={cacheName}

Parameter Type Optional Description

Parameter	Type	Optional	Description
`cacheName`	String	Yes	Cache name.
`backups`	int	Yes	Number of backups for cache data. Default is 0.
`dataRegion`	String	Yes	Name of the data region the cache should belong to.
`templateName`	String	Yes	Name of the cache template registered in Ignite to use as a configuration for the distributed cache. See the Cache Template section for more information.
`cacheGroup`	String	Yes	Name of the group the cache should belong to.
`writeSynchronizationMode`	String	Yes	Sets the write synchronization mode for the given cache: `FULL_SYNC` `FULL_ASYNC` `PRIMARY_SYNC`

cacheName

String

Yes

Cache name.

backups

int

Yes

Number of backups for cache data. Default is 0.

dataRegion

String

Yes

Name of the data region the cache should belong to.

templateName

String

Yes

Name of the cache template registered in Ignite to use as a configuration for the distributed cache. See the Cache Template section for more information.

cacheGroup

String

Yes

Name of the group the cache should belong to.

writeSynchronizationMode

String

Yes

Sets the write synchronization mode for the given cache:

FULL_SYNC
FULL_ASYNC
PRIMARY_SYNC

Response:

{
  "error": "",
  "response": null,
  "successStatus": 0
}

Destroy cache

Destroys cache with given name.

Request:

http://host:port/ignite?cmd=destcache&cacheName={cacheName}

Parameter Type Optional Description Example

Parameter	Type	Optional	Description	Example
`cacheName`	string	Yes	Cache name.	partitionedCache

cacheName

string

Yes

Cache name.

partitionedCache

Response:

{
  "error": "",
  "response": null,
  "successStatus": 0
}

Node

Gets information about a node.

Request:

http://host:port/ignite?cmd=node&attr={includeAttributes}&mtr={includeMetrics}&id={nodeId}&caches={includeCaches}

Parameter Type Optional Description Example

Parameter	Type	Optional	Description	Example
`mtr`	boolean	Yes	Response includes metrics if this parameter is `true`.	`true`
`attr`	boolean	Yes	Response includes attributes if this parameter is `true`.	`true`
`ip`	string		This parameter is optional if the `id` parameter is specified. Response is returned for node which has the given IP.	`192.168.0.1`
`id`	string		This parameter is optional if the `ip` parameter is specified. Response is returned for node which has the given node ID.	`8daab5ea-af83-4d91-99b6-77ed2ca06647`
`caches`	boolean	Yes	When set to `true` the cache information returned by node includes: name, mode, and SQL Schema. When set to `false` the node command does not return any cache information. Default value is `true`.	`true`

mtr

boolean

Yes

Response includes metrics if this parameter is true.

true

attr

boolean

Yes

Response includes attributes if this parameter is true.

true

ip

string

This parameter is optional if the id parameter is specified. Response is returned for node which has the given IP.

192.168.0.1

id

string

This parameter is optional if the ip parameter is specified. Response is returned for node which has the given node ID.

8daab5ea-af83-4d91-99b6-77ed2ca06647

caches

boolean

Yes

When set to true the cache information returned by node includes: name, mode, and SQL Schema.

When set to false the node command does not return any cache information.

Default value is true.

true

Response:

{
  "error": "",
  "response": {
    "attributes": null,
    "caches": {},
    "consistentId": "127.0.0.1:47500",
    "defaultCacheMode": "REPLICATED",
    "metrics": null,
    "nodeId": "2d0d6510-6fed-4fa3-b813-20f83ac4a1a9",
    "replicaCount": 128,
    "tcpAddresses": ["127.0.0.1"],
    "tcpHostNames": [""],
    "tcpPort": 11211
  },
  "successStatus": 0
}

Log

Shows server logs.

Request:

http://host:port/ignite?cmd=log&from={from}&to={to}&path={pathToLogFile}

Parameter Type Optional Description Example

Parameter	Type	Optional	Description	Example
`from`	integer	Yes	Number of line to start from. Parameter is mandatory if to is passed.	`0`
`path`	string	Yes	The path to log file. If not provided the a default one is used.	`/log/cache_server.log`
`to`	integer	Yes	Number to line to finish on. Parameter is mandatory if from is passed.	`1000`

from

integer

Yes

Number of line to start from. Parameter is mandatory if to is passed.

0

path

string

Yes

The path to log file. If not provided the a default one is used.

/log/cache_server.log

to

integer

Yes

Number to line to finish on. Parameter is mandatory if from is passed.

1000

Response:

{
  "error": "",
  "response": ["[14:01:56,626][INFO ][test-runner][GridDiscoveryManager] Topology snapshot [ver=1, nodes=1, CPUs=8, heap=1.8GB]"],
  "successStatus": 0
}

Topology

Gets the information about cluster topology.

Request:

http://host:port/ignite?cmd=top&attr=true&mtr=true&id=c981d2a1-878b-4c67-96f6-70f93a4cd241

Parameter Type Optional Description Example

Parameter	Type	Optional	Description	Example
`mtr`	boolean	Yes	Response will include metrics, if this parameter is `true`.	true
`attr`	boolean	Yes	Response will include attributes, if this parameter is `true`.	true
`ip`	string	Yes	This parameter is optional, if the `id` parameter is passed. Response will be returned for node which has the IP.	192.168.0.1
`id`	string	Yes	This parameter is optional, if the `ip` parameter is passed. Response will be returned for node which has the node ID.	8daab5ea-af83-4d91-99b6-77ed2ca06647
`caches`	boolean	Yes	When set to `true` the cache information returned by top will include: `name`, `mode`, and `SQL Schema`. When set to `false` the top command does not return any cache information. Default value is `true`.	true

mtr

boolean

Yes

Response will include metrics, if this parameter is true.

true

attr

boolean

Yes

Response will include attributes, if this parameter is true.

true

ip

string

Yes

This parameter is optional, if the id parameter is passed. Response will be returned for node which has the IP.

192.168.0.1

id

string

Yes

This parameter is optional, if the ip parameter is passed. Response will be returned for node which has the node ID.

8daab5ea-af83-4d91-99b6-77ed2ca06647

caches

boolean

Yes

When set to true the cache information returned by top will include: name, mode, and SQL Schema. When set to false the top command does not return any cache information. Default value is true.

true

Response:

{
  "error": "",
  "response": [
    {
      "attributes": {
        ...
      },
      "caches": [
        {
          name: "",
          mode: "PARTITIONED"
        },
        {
          name: "partitionedCache",
          mode: "PARTITIONED",
          sqlSchema: "partitionedCache"
        }
      ],
      "consistentId": "127.0.0.1:47500",
      "metrics": {
        ...
      },
      "nodeId": "96baebd6-dedc-4a68-84fd-f804ee1ed995",
      "replicaCount": 128,
      "tcpAddresses": ["127.0.0.1"],
      "tcpHostNames": [""],
      "tcpPort": 11211
   },
   {
     "attributes": {
       ...
     },
		 "caches": [
       {
         name: "",
         mode: "REPLICATED"
       }
     ],
     "consistentId": "127.0.0.1:47501",
     "metrics": {
       ...
     },
     "nodeId": "2bd7b049-3fa0-4c44-9a6d-b5c7a597ce37",
     "replicaCount": 128,
     "tcpAddresses": ["127.0.0.1"],
     "tcpHostNames": [""],
     "tcpPort": 11212
   }
  ],
  "successStatus": 0
}

Execute a Task

Executes a given task in the cluster.

Request:

http://host:port/ignite?cmd=exe&name=taskName&p1=param1&p2=param2&async=true

Parameter Type Optional Description Example

Parameter	Type	Optional	Description	Example
`name`	string		Name of the task to execute.	`summ`
`p1…pN`	string	Yes	Argument of task execution.	arg1…argN
`async`	boolean	Yes	Determines whether the task is performed asynchronously.	`true`

name

string

Name of the task to execute.

summ

p1…pN

string

Yes

Argument of task execution.

arg1…argN

async

boolean

Yes

Determines whether the task is performed asynchronously.

true

Response:

The response contains an error message, unique identifier of the task, the status and result of computation.

{
  "error": "",
  "response": {
    "error": "",
    "finished": true,
    "id": "~ee2d1688-2605-4613-8a57-6615a8cbcd1b",
    "result": 4
  },
  "successStatus": 0
}

Result of a Task

Returns the computation result for a given task.

Request:

http://host:port/ignite?cmd=res&id={taskId}

Parameter Type Optional Description Example

id

string

ID of the task whose result is to be returned.

69ad0c48941-4689aae0-6b0e-4d52-8758-ce8fe26f497d~4689aae0-6b0e-4d52-8758-ce8fe26f497d

Response:

The response contains information about errors (if any), ID of the task, and the status and result of computation.

{
  "error": "",
  "response": {
    "error": "",
    "finished": true,
    "id": "69ad0c48941-4689aae0-6b0e-4d52-8758-ce8fe26f497d~4689aae0-6b0e-4d52-8758-ce8fe26f497d",
    "result": 4
  },
  "successStatus": 0
}

SQL Query Execute

Runs SQL query over cache.

Request:

http://host:port/ignite?cmd=qryexe&type={type}&pageSize={pageSize}&cacheName={cacheName}&arg1=1000&arg2=2000&qry={query}&keepBinary={keepBinary}

Parameter Type Optional Description Example

type

string

Type for the query

String

pageSize

number

Page size for the query.

cacheName

string

Yes

Cache name.

testCache

arg1…argN

string

Query arguments

1000,2000

qry

strings

Encoding sql query

salary+%3E+%3F+and+salary+%3C%3D+%3F

keepBinary

boolean

Yes

Keeps the query results in binary form. Defaults to false. See Binary Objects in Query Results.

true

Response:

The response object contains the items returned by the query, a flag indicating the last page, and queryId.

{
  "error":"",
  "response":{
    "fieldsMetadata":[],
    "items":[
      {"key":3,"value":{"name":"Jane","id":3,"salary":2000}},
      {"key":0,"value":{"name":"John","id":0,"salary":2000}}],
    "last":true,
    "queryId":0},
  "successStatus":0
}

SQL Fields Query Execute

Runs SQL fields query over cache.

Request:

http://host:port/ignite?cmd=qryfldexe&pageSize=10&cacheName={cacheName}&qry={qry}&keepBinary={keepBinary}

Parameter Type Optional Description Example

pageSize

number

Page size for the query.

cacheName

string

Yes

Cache name.

testCache

arg1…argN

string

Query arguments.

1000,2000

qry

strings

Encoding sql fields query.

select+firstName%2C+lastName+from+Person

keepBinary

boolean

Yes

Keeps the query results in binary form. Defaults to false. See Binary Objects in Query Results.

true

Response:

The response object contains the items returned by the query, fields query metadata, a flag indicating the last page, and queryId.

{
  "error": "",
  "response": {
    "fieldsMetadata": [
      {
        "fieldName": "FIRSTNAME",
        "fieldTypeName": "java.lang.String",
        "schemaName": "person",
        "typeName": "PERSON"
      },
      {
        "fieldName": "LASTNAME",
        "fieldTypeName": "java.lang.String",
        "schemaName": "person",
        "typeName": "PERSON"
      }
    ],
    "items": [["Jane", "Doe" ], ["John", "Doe"]],
    "last": true,
    "queryId": 0
  },
  "successStatus": 0
}

SQL Scan Query Execute

Runs a scan query over a cache.

Request:

http://host:port/ignite?cmd=qryscanexe&pageSize={pageSize}&cacheName={cacheName}&className={className}&keepBinary={keepBinary}

Parameter Type Optional Description Example

pageSize

Number

Page size for the query

cacheName

String

Yes

Cache name.

testCache

className

String

Yes

Predicate class name for scan query. Class should implement IgniteBiPredicate interface.

org.apache.ignite.filters.PersonPredicate

keepBinary

Boolean

Yes

Keeps the query results in binary form. Defaults to false. See Binary Objects in Query Results.

true

Response:

The response object contains the items returned by the scan query, fields query metadata, a flag indicating last page, and queryId.

{
  "error": "",
  "response": {
    "fieldsMetadata": [
      {
        "fieldName": "key",
        "fieldTypeName": "",
        "schemaName": "",
        "typeName": ""
      },
      {
        "fieldName": "value",
        "fieldTypeName": "",
        "schemaName": "",
        "typeName": ""
      }
    ],
    "items": [
      {
        "key": 1,
        "value": {
          "firstName": "Jane",
          "id": 1,
          "lastName": "Doe",
          "salary": 1000
        }
      },
      {
        "key": 3,
        "value": {
          "firstName": "Jane",
          "id": 3,
          "lastName": "Smith",
          "salary": 2000
        }
      }
    ],
    "last": true,
    "queryId": 0
  },
  "successStatus": 0
}

SQL Query Fetch

Gets next page for the query.

Request:

http://host:port/ignite?cmd=qryfetch&pageSize={pageSize}&qryId={queryId}

Parameter Type Optional Description Example

pageSize

number

Page size for the query.

qryId

number

Query id that is returned from the Sql query execute, sql fields query execute, or sql fetch commands.

Response:

The response object contains the items returned by the query, a flag indicating the last page, and queryId.

{
  "error":"",
  "response":{
    "fieldsMetadata":[],
    "items":[["Jane","Doe"],["John","Doe"]],
    "last":true,
    "queryId":0
  },
  "successStatus":0
}

SQL Query Close

Closes query resources.

Request:

http://host:port/ignite?cmd=qrycls&qryId={queryId}

Parameter Type Optional Description Example

qryId

number

Query id that is returned from the SQL query execute, SQL fields query execute, or SQL fetch commands.

Response:

The command returns 'true' if the query was closed successfully.

{
  "error":"",
  "response":true,
  "successStatus":0
}

Probe

Probes a node for Kubernetes liveness, readiness, and startup checks. The optional kind query parameter (case-insensitive) selects the check; without it, the command returns whether the Ignite kernel has started.

kind value Meaning

(omitted) or liveness

Liveness. Returns whether the Ignite kernel has started. Backs the livenessProbe. A node that is rebalancing or in maintenance mode is still considered alive.

readiness

Readiness/startup. Returns whether the node is ready to serve traffic. Backs the readinessProbe and startupProbe. A (re)joining node reports not-ready until it has finished pulling its partitions, so a rolling restart does not bounce the next pod mid-rebalance and lose data.

The readiness check is evaluated in order and reports ready only when the kernel has started, the node is not in maintenance mode, the node is not draining, and either the cluster is inactive or the node’s initial rebalance has completed. Once a node completes its initial rebalance it stays ready for the rest of its lifetime; later topology-change rebalances do not flip it back to not-ready.

Request:

http://host:port/ignite?cmd=probe&kind=readiness

Response:

Returns HTTP status code 200 when the check passes, and 503 otherwise. For a failed readiness check, the error field carries the reason: kernel not started, maintenance mode, draining, or rebalance in progress. An unrecognized kind value returns a failed status with the message Unknown probe kind: <value> (expected one of: liveness, readiness).

{
  "error": "",
  "response": "ready",
  "successStatus": 0
}

Drain

Sets, clears, or reads a node’s drain flag — a Kubernetes pod-lifecycle switch for graceful rolling restarts. While the flag is set, cmd=probe&kind=readiness reports 503, so Kubernetes removes the pod from the Service endpoints and stops routing new traffic to it before the pod is terminated. The required action query parameter (case-insensitive) selects the operation.

action value Meaning

start

Sets the drain flag. Under the GRACEFUL shutdown policy, the command is refused with 503 if this node is the sole owner of any cache group’s partitions, so that terminating it would not make that data unavailable; pass force=true to override and accept the data loss. Requires ADMIN_OPS privilege.

stop

Clears the drain flag, returning the node to normal readiness behavior. Requires ADMIN_OPS privilege.

status

Returns whether the drain flag is currently set. Does not require authentication.

The drain flag is held in node memory and is not persisted: it is automatically cleared when the node restarts. The unique-data guard on start applies only under the GRACEFUL shutdown policy; under IMMEDIATE the flag is set without the ownership check.

Request:

http://host:port/ignite?cmd=drain&action=start&force=true

Response:

Returns HTTP status code 200 on success. For action=status, the current flag is carried in the response field:

{
  "error": "",
  "response": {
    "draining": true
  },
  "successStatus": 0
}

When action=start is refused because the node holds the only copy of a cache group’s data, the command returns HTTP status code 503, the error field names the affected cache groups, and the response field lists them:

{
  "error": "unique data held on cache groups: [myCache]",
  "response": {
    "uniqueDataHeld": true,
    "cacheGroups": ["myCache"]
  },
  "successStatus": 503
}

Cache List

Lists the caches, cache groups, or atomic sequences on the cluster. This command is the REST equivalent of control.sh --cache list and reports the same information. The cluster must be active.

By default, the command lists caches.

Pass the groups=true parameter to list cache groups instead, or seq=true parameter to list atomic sequences.

Pass config=true to include each cache’s configuration in the response. This parameter is only compatible with listing caches, so you cannot combine it with groups or seq.

Request:

http://host:port/ignite?cmd=cachelist&regex={regex}&config={config}&nodeId={nodeId}

Parameter Type Optional Description Example

regex

string

Yes

Java regular expression that a cache, cache group, or sequence name must match to be listed. Default value is .*, which matches every name.

cache[12]

groups

boolean

Yes

Set to true to list cache groups instead of caches. Default value is false. Cannot be combined with seq or config.

true

seq

boolean

Yes

Set to true to list atomic sequences instead of caches. Default value is false. Cannot be combined with groups or config.

true

config

boolean

Yes

Set to true to include each cache’s configuration in the response. Default value is false. Cannot be combined with groups or seq.

true

nodeId

string

Yes

ID of the server node that collects the information. Must be a server node. If you omit it, the node that receives the request is used when it is a server node, otherwise the oldest server node in the cluster is used.

8daab5ea-af83-4d91-99b6-77ed2ca06647

Response:

The response field holds an array whose entries describe the objects the requested mode lists:

By default, each entry describes a cache:

{
  "error": null,
  "response": [
    {
      "cacheName": "partitionedCache",
      "cacheId": 1035368619,
      "grpName": "myGroup",
      "grpId": 98629247,
      "prim": 1024,
      "mapped": 1024,
      "mode": "PARTITIONED",
      "atomicity": "ATOMIC",
      "backups": 1,
      "affCls": "RendezvousAffinityFunction",
      "cacheSize": 100
    }
  ],
  "successStatus": 0
}

With groups=true, each entry describes a cache group. The fields are the same as for caches, except that cacheName and cacheId are replaced by cachesCnt:

{
  "error": null,
  "response": [
    {
      "grpName": "myGroup",
      "grpId": 98629247,
      "cachesCnt": 2,
      "prim": 1024,
      "mapped": 1024,
      "mode": "PARTITIONED",
      "atomicity": "ATOMIC",
      "backups": 1,
      "affCls": "RendezvousAffinityFunction",
      "cacheSize": 200
    }
  ],
  "successStatus": 0
}

With seq=true, each entry describes an atomic sequence:

{
  "error": null,
  "response": [
    {
      "seqName": "mySequence",
      "curVal": 1000
    }
  ],
  "successStatus": 0
}

Because a sequence reserves values in batches, curVal is the upper bound of the currently reserved batch and can therefore be greater than the last value the application actually used. If the cluster has no atomic sequences, the command returns an empty array rather than an error.

With config=true, each entry carries the cache name, the number of mapped partitions, and the cache configuration. The configuration object holds the full cache configuration and is abbreviated in the example below:

{
  "error": null,
  "response": [
    {
      "cacheName": "partitionedCache",
      "mapped": 1024,
      "configuration": {
        "name": "partitionedCache",
        "groupName": "myGroup",
        "mode": "PARTITIONED",
        "atomicityMode": "ATOMIC",
        "affinityConfiguration": {
          "function": "RendezvousAffinityFunction",
          "partitions": 1024,
          "partitionedBackups": 1
        }
      }
    }
  ],
  "successStatus": 0
}

When validation fails, the command returns successStatus 1 and describes the problem in the error field.

Cache Distribution

Reports how cache group partitions are distributed across the cluster’s server nodes. This command is the REST equivalent of control.sh --cache distribution and reports the same information. The cluster must be active.

By default, the command collects information from every server node and reports every cache group. Use nodeId to restrict collection to a single node, and caches to restrict the report to the groups that own the named caches.

Request:

http://host:port/ignite?cmd=cachedistribution&caches={caches}&nodeId={nodeId}

Parameter Type Optional Description Example

caches

string

Yes

Comma-separated list of cache names whose groups are reported. If you omit it, every cache group is reported. The command fails if any name in the list is not an existing cache.

cache1,cache2

nodeId

string

Yes

ID of the server node to collect information from. Must be a server node. If you omit it, every server node in the cluster is used.

8daab5ea-af83-4d91-99b6-77ed2ca06647

userAttributes

string

Yes

Comma-separated list of node user attribute names to include in the userAttributes field of each node entry. If you omit it, userAttributes is null. An attribute that a node does not have is reported with a null value.

region,zone

Response:

The response field holds an object whose nodes array carries one entry per node, each listing its cache groups and the partitions the node holds for them:

{
  "error": null,
  "response": {
    "nodes": [
      {
        "nodeId": "8daab5ea-af83-4d91-99b6-77ed2ca06647",
        "addresses": "[127.0.0.1, 192.168.1.5]",
        "userAttributes": {
          "region": "us-east"
        },
        "groups": [
          {
            "groupId": 98629247,
            "groupName": "myGroup",
            "cacheNames": ["cache1", "cache2"],
            "partitions": [
              {
                "partition": 0,
                "primary": true,
                "state": "OWNING",
                "updateCounter": 42,
                "size": 100
              }
            ]
          }
        ]
      }
    ],
    "errors": null
  },
  "successStatus": 0
}

Field Type Description Example

addresses

string

The node’s network addresses, rendered as a single bracketed string.

[127.0.0.1, 192.168.1.5]

userAttributes

jsonObject

The node user attributes named by the userAttributes request parameter.

{"region": "us-east"}

primary

boolean

Whether the node holds this partition as primary. false means it holds a backup copy.

true

state

string

Partition state on this node. One of MOVING, OWNING, RENTING, EVICTED, or LOST.

OWNING

updateCounter

number

Partition update counter, which you can compare across nodes to spot divergence.

size

number

Number of entries in the partition on this node.

100

The errors field is null when every node succeeded. When collection fails on some nodes, errors maps each failed node’s ID to its error message, and those nodes are omitted from the nodes array, which still reports the nodes that succeeded:

{
  "error": null,
  "response": {
    "nodes": [],
    "errors": {
      "8daab5ea-af83-4d91-99b6-77ed2ca06647": "Failed to collect distribution"
    }
  },
  "successStatus": 0
}

When validation fails, the command returns successStatus 1 and describes the problem in the error field.

List Properties

Lists all distributed properties available on the cluster. This command is the REST equivalent of control.sh --property list.

Request:

http://host:port/ignite?cmd=listproperties

Response:

{
  "error": "",
  "response": [
    {
      "name": "baselineAutoAdjustEnabled",
      "value": "true",
      "type": "Boolean"
    },
    {
      "name": "sql.disabledFunctions",
      "value": null,
      "type": null
    }
  ],
  "successStatus": 0
}

A null value and type mean the property is not set; the cluster uses its built-in default.

Get Property

Returns the current value of a single distributed property.

Request:

http://host:port/ignite?cmd=getproperty&name={propertyName}

Parameter Type Optional Description Example

name

string

Name of the distributed property to read.

baselineAutoAdjustEnabled

Response:

{
  "error": "",
  "response": {
    "name": "baselineAutoAdjustEnabled",
    "value": "true",
    "type": "Boolean"
  },
  "successStatus": 0
}

If the named property is not registered on the cluster, the response uses a non-zero successStatus and the error field contains Unknown distributed property: {name}.

Set Property

Sets the value of a distributed property cluster-wide.

Request:

http://host:port/ignite?cmd=setproperty&name={propertyName}&val={propertyValue}

Parameter Type Optional Description Example

name

string

Name of the distributed property to set.

baselineAutoAdjustEnabled

val

string

New value. The value is parsed according to the property’s declared type.

true

Response:

{
  "error": "",
  "response": {
    "name": "baselineAutoAdjustEnabled",
    "value": "true",
    "type": "Boolean"
  },
  "successStatus": 0
}

If the named property is not registered, or the supplied value fails to parse, the response uses a non-zero successStatus and the error field describes the failure.

© 2026 GridGain Systems, Inc. All Rights Reserved. Privacy Policy | Legal Notices. GridGain® is a registered trademark of GridGain Systems, Inc.
Apache, Apache Ignite, the Apache feather and the Apache Ignite logo are either registered trademarks or trademarks of The Apache Software Foundation.

Last updated on Sep 10, 2026