Apache Ignite Documentation

GridGain Developer Hub - Apache Ignitetm

Welcome to the Apache Ignite developer hub run by GridGain. Here you'll find comprehensive guides and documentation to help you start working with Apache Ignite as quickly as possible, as well as support if you get stuck.

 

GridGain also provides Community Edition which is a distribution of Apache Ignite made available by GridGain. It is the fastest and easiest way to get started with Apache Ignite. The Community Edition is generally more stable than the Apache Ignite release available from the Apache Ignite website and may contain extra bug fixes and features that have not made it yet into the release on the Apache website.

 

Let's jump right in!

 

Documentation     Ask a Question     Download

 

Javadoc     Scaladoc     Examples

REST API

Connect to Ignite over HTTP REST protocol.

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

Getting Started

To enable HTTP connectivity, make sure that ignite-rest-http module is in the classpath of your application. With Ignite binary distribution, this means copying ignite-rest-http module from IGNITE_HOME/libs/optional/ to IGNITE_HOME/libs folder.

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'

Security

Ignite allows you to establish a secure connection to the cluster via the REST protocol. For this, make sure that authentication is enabled on the cluster via the IgniteConfiguration.setAuthenticationEnabled(true) method. Note that currently authentication is available only when persistence is enabled.

Enable authentication

Authentication for Ignite nodes can be enabled via the IgniteConfiguration.setAuthenticationEnabled(true) method. Currently, authentication is supported only when Ignite persistence is enabled. This requirement may be relaxed in future releases.

When authentication is enabled on the server, you can request user authorization by providing user=[user]&password=[password] parameters in the REST connection string. Doing so will provide you with 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 user=[user]&password=[password] parameters.
https://[host]:[port]/ignite?cmd=authenticate&user=[user]&password=[password]
  1. Use any REST command with user=[user]&password=[password] parameters in the path of your connection string. In our example below, we have used the version command:
 http://[host]:[port]/ignite?cmd=version&user=[user]&password=[password]

In both the examples above, replace [host], [port], [user] and [password] values with actual values.

Executing any one of the above strings in a browser will provide a response with a session token which will look something 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.

Note that 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 a REST connection string will result 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 will result 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 system variable: IGNITE_REST_SESSION_TIMEOUT (in seconds).

For example, -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 will exchange the key-value data in String format. This means that the data will be 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

API Reference

Returned value

HTTP REST request returns JSON object which has similar structure for each command. This object has the following structure:

name
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 turned on - 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

Log

Log command shows server logs.

http://host:port/ignite?cmd=log&from=10&to=100&path=/var/log/ignite.log

Request Parameters

name
type
optional
decription
example

cmd

string

No

Should be log lowercase.

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 example:

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

response

string

logs

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

Version

Version command shows current Ignite version.

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

Request Parameters

name
type
optional
description
example

cmd

string

Should be version lowercase.

Response example

{
  "error": "",
  "response": "1.0.0",
  "successStatus": 0
}
name
type
description
example

response

string

Ignite version

1.0.0

Activate

Activate command starts the cluster activation process for a persistence-enabled cluster.

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

Request Parameters

name
type
optional
description
example

cmd

string

Should be activate lowercase.

Response example

{
  "successStatus":0,
  "error":null,
  "sessionToken":null,
  "response":"activate started"
}
name
type
description
example

response

string

Starts cluster activation.

activate started

Deactivate

Deactivate command starts the deactivation process for a persistence-enabled cluster.

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

Request Parameters

name
type
optional
description
example

cmd

string

Should be deactivate lowercase.

Response example

{
  "successStatus":0,
  "error":null,
  "sessionToken":null,
  "response":"deactivate started"
}
name
type
description
example

response

string

Starts cluster deactivation

deactivate started

Currentstate

Currentstate command shows the current state(active/deactive) of the Ignite cluster.

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

Request Parameters

name
type
optional
description
example

cmd

string

Should be currentstate lowercase.

Response example

{
  "successStatus":0,
  "error":null,
  "sessionToken":null,
  "response":true
}
name
type
description
example

response

string

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

true

Decrement

Decrement command subtracts and gets current value of given atomic long.

http://host:port/ignite?cmd=decr&cacheName=partionedCache&key=decrKey&init=15&delta=10

Request parameters

name
type
optional
decription
example

cmd

string

Should be decr lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

key

string

The name of atomic long.

counter

init

long

Yes

Initial value.

15

delta

long

Number to be subtracted.

42

Response example

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

response

long

Value after operation.

-42

Increment

Increment command adds and gets current value of given atomic long.

http://host:port/ignite?cmd=incr&cacheName=partionedCache&key=incrKey&init=15&delta=10

Request parameters

name
type
optional
decription
example

cmd

string

Should be incr lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

key

string

The name of atomic long.

counter

init

long

Yes

Initial value.

15

delta

long

Number to be added.

42

Response example

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

response

long

Value after operation.

42

Cache metrics

Cache metrics command shows metrics for Ignite cache.

http://host:port/ignite?cmd=cache&cacheName=partionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request parameters

name
type
optional
decription
example

cmd

string

Should be cache lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

destId

string

Yes

Node ID for which the metrics are to be returned.

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

Response example

{
  "affinityNodeId": "",
  "error": "",
  "response": {
    "hits": 0,
    "misses": 0,
    "reads": 0,
    "writes": 2
  },
  "successStatus": 0
}
name
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
}

Compare-And-Swap

CAS command stores given key-value pair in cache only if the previous value is equal to the expected value passed in.

http://host:port/ignite?cmd=cas&key=casKey&val2=casOldVal&val1=casNewVal&cacheName=partionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request parameters

name
type
optional
decription
example

cmd

string

Should be cas lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

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 example

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

response

boolean

True if replace happened, false otherwise.

true

Prepend

Prepend command prepends a line for value which is associated with key.

http://host:port/ignite?cmd=prepend&key=prependKey&val=prefix_&cacheName=partionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request parameters

name
type
optional
decription
example

cmd

string

Should be prepend lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

key

string

Key to store in cache.

name

val

string

Value 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 example

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

response

boolean

True if replace happened, false otherwise.

true

Append

Append command appends a line for value which is associated with key.

http://host:port/ignite?cmd=append&key=appendKey&val=_suffix&cacheName=partionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request parameters

name
type
optional
decription
example

cmd

string

Should be append lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

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 example

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

response

boolean

True if replace happened, false otherwise.

true

Replace

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

http://host:port/ignite?cmd=rep&key=repKey&val=newValue&cacheName=partionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request parameters

name
type
optional
decription
example

cmd

string

Should be rep lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

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 example

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

response

boolean

True if replace happened, false otherwise.

true

Get and replace

Get and replace command stores a given key-value pair in cache only if there is a previous mapping for it.

http://host:port/ignite?cmd=getrep&key=repKey&val=newValue&cacheName=partionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request parameters

name
type
optional
decription
example

cmd

string

Should be getrep lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

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 example

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

response

jsonObject

The previous value associated with the specified key.

{"name": "Bob"}

Replace Value

Replace Value command replaces the entry for a key only if currently mapped to a given value.

http://host:port/ignite?cmd=repval&key=repKey&val=newValue&val2=oldVal&cacheName=partionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request parameters

name
type
optional
decription
example

cmd

string

Should be repval lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

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 example

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

response

boolean

True if replace happened, false otherwise.

true

Remove all

Remove all command removes given key mappings from cache.

http://host:port/ignite?cmd=rmvall&k1=rmKey1&k2=rmKey2&k3=rmKey3&cacheName=partionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request parameters

name
type
optional
decription
example

cmd

string

Should be rmvall lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

k1...kN

string

Keys whose mappings are 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 example

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

response

boolean

True if replace happened, false otherwise.

true

Remove value

Remove value command removes the mapping for a key only if currently mapped to the given value.

http://host:port/ignite?cmd=rmvval&key=rmvKey&val=rmvVal&cacheName=partionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request parameters

name
type
optional
decription
example

cmd

string

Should be rmvval lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

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 example

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

response

boolean

False if there was no matching key

true

Remove

Remove command removes the given key mapping from cache.

http://host:port/ignite?cmd=rmv&key=rmvKey&cacheName=partionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request parameters

name
type
optional
decription
example

cmd

string

Should be rmv lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

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 example

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

response

boolean

True if replace happened, false otherwise.

true

Get and remove

Get and remove command removes the given key mapping from cache and returns previous value.

http://host:port/ignite?cmd=getrmv&cacheName=partionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647&key=name
 

Request parameters

name
type
optional
decription
example

cmd

string

Should be getrmv lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

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 example

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

response

jsonObject

Value for the key.

{"name": "bob"}

Add

Add command stores a given key-value pair in cache only if there isn't a previous mapping for it.

http://host:port/ignite?cmd=add&key=newKey&val=newValue&cacheName=partionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request parameters

name
type
optional
decription
example

cmd

string

Should be add lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

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

Response example

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

response

boolean

True if value was stored in cache, false otherwise.

true

Put all

Put all command stores the given key-value pairs in cache.

http://host:port/ignite?cmd=putall&k1=putKey1&k2=putKey2&k3=putKey3&v1=value1&v2=value2&v3=value3&cacheName=partionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request parameters

name
type
optional
decription
example

cmd

string

Should be putall lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

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 example

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

response

boolean

True if values was stored in cache, false otherwise.

true

Put

Put command stores the given key-value pair in cache.

http://host:port/ignite?cmd=put&key=newKey&val=newValue&cacheName=partionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request parameters

name
type
optional
decription
example

cmd

string

Should be put lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

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

Response example

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

response

boolean

True if value was stored in cache, false otherwise.

true

Get all

Getall command retrieves values mapped to the specified keys from cache.

http://host:port/ignite?cmd=getall&k1=getKey1&k2=getKey2&k3=getKey3&cacheName=partionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request parameters

name
type
optional
decription
example

cmd

string

Should be getall lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

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 example

{
  "affinityNodeId": "",
  "error": "",
  "response": {
    "key1": "value1",
    "key2": "value2"
  },
  "successStatus": 0
}
name
type
description
example

response

jsonObject

The map of key-value pairs.

{"key1": "value1","key2": "value2"}

Get output as array

To obtain the output as an array, use the IGNITE_REST_GETALL_AS_ARRAY=true system property. Once the property is set, the getall command will provide the response in the following format:
{“successStatus”:0,“affinityNodeId”:null,“error”:null,“sessionToken”:null,“response”:[{“key”:“key1”,“value”:“value1”},{“key”:“key2”,“value”:“value2”}]}

Get

Get command retrieves value mapped to the specified key from cache.

http://host:port/ignite?cmd=get&key=getKey&cacheName=partionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

You can also get objects that were inserted via API, or SQL. For example, if you have a "Person" object in cache, you can obtain it the following way:

# If the entry in cache was inserted via API, for example
# cache.put(1, new Person(1, Alex, 300));
# you can use the following REST command to get the value

http://host:port/ignite?cmd=get&cacheName=myCacheName&keyType=int&key=1
# If the entry in cache was inserted via SQL, for example -
# create table person(id integer primary key, name varchar(100), salary integer);
# insert into person(id, name, salary) values (1, Alex, 300);
# you can use the following REST command to get the value

http://host:port/ignite?cmd=get&cacheName=SQL_PUBLIC_PERSON&keyType=int&key=1

Request parameters

name
type
optional
decription
example

cmd

string

Should be get lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

key

string

Key whose associated value is to be returned

testKey

keyType

Java built-in type

Yes

See Data Types section for more details

destId

string

Yes

Node ID for which the metrics are to be returned.

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

Response example

{
  "affinityNodeId": "2bd7b049-3fa0-4c44-9a6d-b5c7a597ce37",
  "error": "",
  "response": "value from cache",
  "successStatus": 0
}
name
type
description
example

response

jsonObject

Value for the given key.

{"name": "Alex","id":1,"salary":2000}

Contains key

Contains key command determines if cache containes an entry for the specified key.

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

Request parameters

name
type
optional
description
example

cmd

string

Should be conkey lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

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 example

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

response

boolean

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

true

Contains keys

Contains keys command determines if cache containes an entries for the specified keys.

http://host:port/ignite?cmd=conkeys&k1=getKey1&k2=getKey2&k3=getKey3&cacheName=partionedCache

Request parameters

name
type
optional
description
example

cmd

string

Should be conkeys lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

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 example

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

response

boolean

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

true

Get and put

Get and put command stores the given key-value pair in cache and returns an existing value if one existed.

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

Request parameters

name
type
optional
description
example

cmd

string

Should be getput lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

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 example

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

response

jsonObject

Previous value for the given key.

{"name": "bob"}

Put if absent

Put if absent command stores given key-value pair in cache only if cache had no previous mapping for it.

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

Request parameters

name
type
optional
description
example

cmd

string

Should be putifabs lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

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 example

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

response

boolean

True if a value was set.

true

Get and put if absent

Get and put if absent command 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.

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

Request parameters

name
type
optional
description
example

cmd

string

Should be getputifabs lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

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 example

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

response

jsonObject

Previous value for the given key.

{"name": "bob"}

Cache size

Cache size command gets the number of all entries cached across all nodes.

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

Request parameters

name
type
optional
description
example

cmd

string

Should be size lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

Response example

{
  "affinityNodeId": "",
  "error": "",
  "response": 1,
  "successStatus": 0
}
name
type
description
example

response

number

Number of all entries cached across all nodes.

5

Cache metadata

Cache metadata command gets metadata for Ignite cache.

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

Request parameters

name
type
optional
description
example

cmd

String

Should be metadata lowercase.

cacheName

String

Yes

Cache name. If not provided, metadata for all user caches will be returned.

partionedCache

Response example

{
  "error": "",
  "response": {
    "cacheName": "partionedCache",
    "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
}
name
type
description
example

response

jsonObject

Metadata for Ignite cache.

{
"cacheName": "partionedCache",
"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
}
]
}
}

Get or create cache

Get or create cache command creates a cache with the given name if it does not exist.

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

Request parameters

name
type
optional
description

cmd

String

Should be getorcreate lowercase.

cacheName

String

Yes

Cache name. If not provided, default cache will be used.

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 Cache Template docs 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 example

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

Destroy cache

Destroy cache command destroys cache with given name.

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

Request parameters

name
type
optional
description
example

cmd

string

Should be destcache lowercase.

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

partionedCache

Response example

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

Node

Node command gets information about a node.

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

Request parameters

name
type
optional
decription
example

cmd

string

Should be node lowercase.

mtr

boolean

Yes

Response will include metrics, if this parameter has value true.

true

attr

boolean

Yes

Response will include attributes, if this parameter has value true.

true

ip

string

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

192.168.0.1

id

string

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

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

Response example

{
  "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
}
name
type
description
example

response

jsonObject

Information about only one node.

{
"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
}

Topology

Topology command gets information about grid topology.

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

Request parameters

name
type
optional
decription
example

cmd

string

Should be top lowercase.

mtr

boolean

Yes

Response will include metrics, if this parameter has value true.

true

attr

boolean

Yes

Response will include attributes, if this parameter has value true.

true

ip

string

Yes

This parameter is optional, if 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 ip parameter is passed. Response will be returned for node which has the node ID.

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

Response example

{
  "error": "",
  "response": [
    {
      "attributes": {
        ...
      },
      "caches": [
        {
          name: "",
          mode: "PARTITIONED"
        },
        {
          name: "partionedCache",
          mode: "PARTITIONED",
          sqlSchema: "partionedCache"
        }
      ],
      "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
}
name
type
description
example

response

jsonObject

Information about grid topology.

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

Execute

Execute command executes given task on grid.

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

Request parameters

name
type
optional
decription
example

cmd

string

Should be exe lowercase.

name

string

Name of the task to execute.

summ

p1...pN

string

Yes

Argument of task execution.

arg1...argN

async

boolean

Yes

The flag determines whether the task is performed asynchronously.

true

Response example

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

response

jsonObject

JSON object contains message about error, unique identifier of task, result of computation and status of computation.

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

Result

Result command returns computation result for the given task.

http://host:port/ignite?cmd=res&id=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request parameters

name
type
optional
decription
example

cmd

string

Should be res lowercase.

id

string

ID of the task whose result is to be returned.

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

Response example

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

response

jsonObject

JSON object contains message about error, ID of task, result of computation and status of computation.

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

Sql query execute

Sql query execute command runs sql query over cache.

http://host:port/ignite?cmd=qryexe&type=Person&pageSize=10&cacheName=Person&arg1=1000&arg2=2000&qry=salary+%3E+%3F+and+salary+%3C%3D+%3F

Request parameters

name
type
optional
decription
example

cmd

string

Should be qryexe lowercase.

type

string

Type for the query

String

pageSize

number

Page size for the query

3

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

testCache

arg1...argN

string

Qyery arguments

1000,2000

qry

strings

Encoding sql query

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

Response example

{
  "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
}
name
type
description
example

response

jsonObject

JSON object contains result items for query, flag for last page and queryId for query fetching.

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

Sql fields query execute

Sql fields query execute command runs sql fields query over cache.

http://host:port/ignite?cmd=qryfldexe&pageSize=10&cacheName=Person&qry=select+firstName%2C+lastName+from+Person

Request parameters

name
type
optional
decription
example

cmd

string

Should be qryfldexe lowercase.

pageSize

number

Page size for the query

3

cacheName

string

Yes

Cache name. If not provided, default cache will be used.

testCache

arg1...argN

string

Qyery arguments

1000,2000

qry

strings

Encoding sql fields query

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

Response example

{
  "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
}
name
type
description
example

response

jsonObject

JSON object contains result items for query, fields query metadata, flag for last page and queryId for query fetching.

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

Sql scan query execute

Sql scan query execute command runs sql scan query over cache.

http://host:port/ignite?cmd=qryscanexe&pageSize=10&cacheName=Person&className=org.apache.ignite.schema.Person

Request parameters

name
type
optional
decription
example

cmd

String

Should be qryscanexe lowercase.

pageSize

Number

Page size for the query

3

cacheName

String

Yes

Cache name. If not provided, default cache will be used.

testCache

className

String

Yes

Predicate class name for scan query.

org.apache.ignite.schema.Person

Response example

{
  "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
}
name
type
description
example

response

jsonObject

JSON object contains result items for scan query, fields query metadata, flag for last page and queryId for query fetching.

{
"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
}

Sql query fetch

Sql query fetch command gets next page for the query.

http://host:port/ignite?cmd=qryfetch&pageSize=10&qryId=5

Request parameters

name
type
optional
decription
example

cmd

string

Should be qryfetch lowercase.

pageSize

number

Page size for the query.

3

qryId

number

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

0

Response example

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

response

jsonObject

JSON object contains result items for query, flag for last page and queryId for query fetching.

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

Sql query close

Sql query close command closes query resources.

http://host:port/ignite?cmd=qrycls&qryId=5

Request parameters

name
type
optional
decription
example

cmd

string

Should be qrycls lowercase.

qryId

number

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

0

Response example

{
  "error":"",
  "response":true,
  "successStatus":0
}
name
type
description
example

response

boolean

True if query closed successfully.

true

General Configuration

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. In case port provided in Jetty configuration or IGNITE_JETTY_PORT system property is already in use, Ignite will iteratively increment port by 1 and try binding 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 not provided then GridGain will start Jetty server with simple HTTP connector. This connector will use IGNITE_JETTY_HOST and IGNITE_JETTY_PORT system properties as host and port respectively. In case IGNITE_JETTY_HOST is not provided, localhost will be used as default. In case IGNITE_JETTY_PORT is not provided, port 8080 will be used as default.

Yes

null

setMessageInterceptor(ConnectorMessageInterceptor)

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

Yes

null

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