REST API | GridGain Documentation

Getting Started

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

When authentication is enabled on the server, you can request user authorization by providing ignite.login=[user]&ignite.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:

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

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

Use any REST command with ignite.login=[user]&ignite.password=[password] parameters in the path of your connection string. In our example below, we have used the version command:
http://[host]:[port]/ignite?cmd=version&ignite.login=[user]&ignite.password=[password]
In both of 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.

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

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

boolean

java.lang.Boolean

byte

java.lang.Byte

short

java.lang.Short

integer

java.lang.Integer

long

java.lang.Long

float

java.lang.Float

double

java.lang.Double

date

java.sql.Date

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

Example: 2018-01-01

time

java.sql.Time

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

Example: 01:01:01

timestamp

java.sql.Timestamp

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

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

uuid

java.util.UUID

IgniteUuid

org.apache.ignite.lang.IgniteUuid

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

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

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

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

API Reference

Internally, Ignite uses Jetty server to provide HTTP server features. HTTP REST client is configured via the ConnectorConfiguration bean.

General Configuration
Sample Jetty XML Configuration

Returned Value

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

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

Log

Shows server logs.

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

Request Parameters

Name

Type

Optional

Description

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

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

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

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

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

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

true

Decrement

Subtracts and gets current value of given atomic long.

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

Request Parameters

Name

Type

Optional

Description

Example

cmd

string

Should be decr lowercase.

cacheName

string

Yes

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

partitionedCache

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

Adds and gets current value of given atomic long.

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

Request Parameters

Name

Type

Optional

Description

Example

cmd

string

Should be incr lowercase.

cacheName

string

Yes

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

partitionedCache

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

Shows metrics for Ignite cache.

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

Request Parameters

Name

Type

Optional

Description

Example

cmd

string

Should be cache lowercase.

cacheName

string

Yes

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

partitionedCache

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

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

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

Request Parameters

Name

Type

Optional

Description

Example

cmd

string

Should be cas lowercase.

cacheName

string

Yes

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

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

Prepends a line for value which is associated with key.

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

Request Parameters

Name

Type

Optional

Description

Example

cmd

string

Should be prepend lowercase.

cacheName

string

Yes

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

partitionedCache

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

Appends a line for value which is associated with key.

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

Request Parameters

Name

Type

Optional

Description

Example

cmd

string

Should be append lowercase.

cacheName

string

Yes

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

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

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=partitionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request Parameters

Name

Type

Optional

Description

Example

cmd

string

Should be rep lowercase.

cacheName

string

Yes

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

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

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=partitionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request Parameters

Name

Type

Optional

Description

Example

cmd

string

Should be getrep lowercase.

cacheName

string

Yes

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

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

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=partitionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request Parameters

Name

Type

Optional

Description

Example

cmd

string

Should be repval lowercase.

cacheName

string

Yes

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

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

Removes given key mappings from cache.

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

Request Parameters

Name

Type

Optional

Description

Example

cmd

string

Should be rmvall lowercase.

cacheName

string

Yes

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

partitionedCache

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

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=partitionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request Parameters

Name

Type

Optional

Description

Example

cmd

string

Should be rmvval lowercase.

cacheName

string

Yes

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

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

Removes the given key mapping from cache.

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

Request Parameters

Name

Type

Optional

Description

Example

cmd

string

Should be rmv lowercase.

cacheName

string

Yes

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

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

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

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

Request Parameters

Name

Type

Optional

Description

Example

cmd

string

Should be getrmv lowercase.

cacheName

string

Yes

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

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

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=partitionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request Parameters

Name

Type

Optional

Description

Example

cmd

string

Should be add lowercase.

cacheName

string

Yes

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

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

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

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=partitionedCache&destId=8daab5ea-af83-4d91-99b6-77ed2ca06647

Request Parameters

Name

Type

Optional

Description

Example

cmd

string

Should be putall lowercase.

cacheName

string

Yes

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

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 Example

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

Name

Type

Description

Example

response

boolean

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

true

Put

Stores the given key-value pair in cache.

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

Request Parameters

Name

Type

Optional

Description

Example

cmd

string

Should be put lowercase.

cacheName

string

Yes

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

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

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

Retrieves values mapped to the specified keys from cache.

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

Request Parameters

Name

Type

Optional

Description

Example

cmd

string

Should be getall lowercase.

cacheName

string

Yes

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

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

Retrieves value mapped to the specified key from cache.

http://host:port/ignite?cmd=get&key=getKey&cacheName=partitionedCache&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

Description

Example

cmd

string

Should be get lowercase.

cacheName

string

Yes

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

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

Response Example

# 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

Name

Type

Description

Example

response

jsonObject

Value for the given key.

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

Contains key

Determines if cache contains an entry for the specified key.

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

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.

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

Determines if cache contains any entries for the specified keys.

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

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.

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

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=partitionedCache

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.

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

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=partitionedCache

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.

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

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=partitionedCache

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.

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

Gets the number of all entries cached across all nodes.

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

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.

partitionedCache

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

Gets metadata for Ignite cache.

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

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.

partitionedCache

Response Example

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

Name

Type

Description

Example

response

jsonObject

Metadata for Ignite cache.

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

Get or create cache

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

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

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

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

Destroy cache

Destroys cache with given name.

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

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.

partitionedCache

Response Example

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

Node

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

Description

Example

cmd

string

Should be node lowercase.

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

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

caches

boolean

Yes

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

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

Default value is true.

true

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

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

Description

Example

cmd

string

Should be top lowercase.

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

Response Example

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

Name

Type

Description

Example

response

jsonObject

Information about grid topology.

[ { "attributes": { … }, "caches": [ { name: "", mode: "PARTITIONED" }, { name: "partitionedCache", mode: "PARTITIONED", sqlSchema: "partitionedCache" } ], "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

Executes given task on grid.

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

Request Parameters

Name

Type

Optional

Description

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

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

Returns computation result for the given task.

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

Request Parameters

Name

Type

Optional

Description

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

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

Description

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

Query 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

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

Description

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

Query 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

Runs scan query over cache.

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

Request Parameters

Name

Type

Optional

Description

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. Class should implement IgniteBiPredicate interface.

org.apache.ignite.filters.PersonPredicate

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

Gets next page for the query.

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

Request Parameters

Name

Type

Optional

Description

Example

cmd

string

Should be qryfetch lowercase.

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

Closes query resources.

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

Request Parameters

Name

Type

Optional

Description

Example

cmd

string

Should be qrycls lowercase.

qryId

number

Query id that is returned from the 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. If the 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 a simple HTTP connector. This connector will use IGNITE_JETTY_HOST and IGNITE_JETTY_PORT system properties as host and port respectively. If IGNITE_JETTY_HOST is not provided, localhost will be used as default. If IGNITE_JETTY_PORT is not provided, port 8080 will be used as default.

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

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>