GridGain Developers Hub

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

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:

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

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

  2. 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.

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

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;
    }
});

Returned Value

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

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

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

key

string

The name of atomic long.

counter

init

long

Yes

Initial value.

15

delta

long

Number to be added.

42
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

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

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

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

cacheName

string

Yes

Cache name.

partitionedCache
Response:
{
  "affinityNodeId": "",
  "error": "",
  "response": 1,
  "successStatus": 0
}
Field Type Description Example

response

number

Number of all entries cached across all nodes.

5

Cache Metadata

Gets metadata for a cache.

Request:
http://host:port/ignite?cmd=metadata&cacheName={cacheName}
Parameter Type Optional Description Example

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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}
Parameter Type Optional Description Example

type

string

Type for the query

String

pageSize

number

Page size for the query.

3

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
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}
Parameter Type Optional Description Example

pageSize

number

Page size for the query.

3

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
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}
Parameter Type Optional Description Example

pageSize

Number

Page size for the query

3

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
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.

3

qryId

number

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

0
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.

0
Response:

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

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

Probe

Returns whether Ignite kernal as started.

Request:
http://host:port/ignite?cmd=probe
Response:

Returns HTTP Status code 200 if kernal has started, and 503 otherwise

{
  "error": "",
  "response": "grid has started",
  "successStatus": 0
}

© 2025 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 Oct 27, 2025