Chapter 2. Interacting with the Data Grid REST API
The Data Grid REST API lets you monitor, maintain, and manage Data Grid deployments and provides access to your data.
By default Data Grid REST API operations return 200 (OK) when successful. However, when some operations are processed successfully, they return an HTTP status code such as 204 or 202 instead of 200.
2.1. Creating and Managing Caches
Create and manage Data Grid caches and perform operations on data.
2.1.1. Creating Caches
Create named caches across Data Grid clusters with POST requests that include XML or JSON configuration in the payload.
POST /rest/v2/caches/{cacheName}Table 2.1. Headers
| Header | Required or Optional | Parameter |
|---|---|---|
|
| REQUIRED |
Sets the MediaType for the Data Grid configuration payload; either |
|
| OPTIONAL | Used to set AdminFlags |
2.1.1.1. Cache configuration
You can create declarative cache configuration in XML, JSON, and YAML format.
All declarative caches must conform to the Data Grid schema. Configuration in JSON format must follow the structure of an XML configuration, elements correspond to objects and attributes correspond to fields.
Data Grid restricts characters to a maximum of 255 for a cache name or a cache template name. If you exceed this character limit, Data Grid throws an exception. Write succinct cache names and cache template names.
A file system might set a limitation for the length of a file name, so ensure that a cache’s name does not exceed this limitation. If a cache name exceeds a file system’s naming limitation, general operations or initialing operations towards that cache might fail. Write succinct file names.
Distributed caches
XML
<distributed-cache owners="2"
segments="256"
capacity-factor="1.0"
l1-lifespan="5000"
mode="SYNC"
statistics="true">
<encoding media-type="application/x-protostream"/>
<locking isolation="REPEATABLE_READ"/>
<transaction mode="FULL_XA"
locking="OPTIMISTIC"/>
<expiration lifespan="5000"
max-idle="1000" />
<memory max-count="1000000"
when-full="REMOVE"/>
<indexing enabled="true"
storage="local-heap">
<index-reader refresh-interval="1000"/>
<indexed-entities>
<indexed-entity>org.infinispan.Person</indexed-entity>
</indexed-entities>
</indexing>
<partition-handling when-split="ALLOW_READ_WRITES"
merge-policy="PREFERRED_NON_NULL"/>
<persistence passivation="false">
<!-- Persistent storage configuration. -->
</persistence>
</distributed-cache>
JSON
{
"distributed-cache": {
"mode": "SYNC",
"owners": "2",
"segments": "256",
"capacity-factor": "1.0",
"l1-lifespan": "5000",
"statistics": "true",
"encoding": {
"media-type": "application/x-protostream"
},
"locking": {
"isolation": "REPEATABLE_READ"
},
"transaction": {
"mode": "FULL_XA",
"locking": "OPTIMISTIC"
},
"expiration" : {
"lifespan" : "5000",
"max-idle" : "1000"
},
"memory": {
"max-count": "1000000",
"when-full": "REMOVE"
},
"indexing" : {
"enabled" : true,
"storage" : "local-heap",
"index-reader" : {
"refresh-interval" : "1000"
},
"indexed-entities": [
"org.infinispan.Person"
]
},
"partition-handling" : {
"when-split" : "ALLOW_READ_WRITES",
"merge-policy" : "PREFERRED_NON_NULL"
},
"persistence" : {
"passivation" : false
}
}
}
YAML
distributedCache:
mode: "SYNC"
owners: "2"
segments: "256"
capacityFactor: "1.0"
l1Lifespan: "5000"
statistics: "true"
encoding:
mediaType: "application/x-protostream"
locking:
isolation: "REPEATABLE_READ"
transaction:
mode: "FULL_XA"
locking: "OPTIMISTIC"
expiration:
lifespan: "5000"
maxIdle: "1000"
memory:
maxCount: "1000000"
whenFull: "REMOVE"
indexing:
enabled: "true"
storage: "local-heap"
indexReader:
refreshInterval: "1000"
indexedEntities:
- "org.infinispan.Person"
partitionHandling:
whenSplit: "ALLOW_READ_WRITES"
mergePolicy: "PREFERRED_NON_NULL"
persistence:
passivation: "false"
# Persistent storage configuration.
Replicated caches
XML
<replicated-cache segments="256"
mode="SYNC"
statistics="true">
<encoding media-type="application/x-protostream"/>
<locking isolation="REPEATABLE_READ"/>
<transaction mode="FULL_XA"
locking="OPTIMISTIC"/>
<expiration lifespan="5000"
max-idle="1000" />
<memory max-count="1000000"
when-full="REMOVE"/>
<indexing enabled="true"
storage="local-heap">
<index-reader refresh-interval="1000"/>
<indexed-entities>
<indexed-entity>org.infinispan.Person</indexed-entity>
</indexed-entities>
</indexing>
<partition-handling when-split="ALLOW_READ_WRITES"
merge-policy="PREFERRED_NON_NULL"/>
<persistence passivation="false">
<!-- Persistent storage configuration. -->
</persistence>
</replicated-cache>
JSON
{
"replicated-cache": {
"mode": "SYNC",
"segments": "256",
"statistics": "true",
"encoding": {
"media-type": "application/x-protostream"
},
"locking": {
"isolation": "REPEATABLE_READ"
},
"transaction": {
"mode": "FULL_XA",
"locking": "OPTIMISTIC"
},
"expiration" : {
"lifespan" : "5000",
"max-idle" : "1000"
},
"memory": {
"max-count": "1000000",
"when-full": "REMOVE"
},
"indexing" : {
"enabled" : true,
"storage" : "local-heap",
"index-reader" : {
"refresh-interval" : "1000"
},
"indexed-entities": [
"org.infinispan.Person"
]
},
"partition-handling" : {
"when-split" : "ALLOW_READ_WRITES",
"merge-policy" : "PREFERRED_NON_NULL"
},
"persistence" : {
"passivation" : false
}
}
}
YAML
replicatedCache:
mode: "SYNC"
segments: "256"
statistics: "true"
encoding:
mediaType: "application/x-protostream"
locking:
isolation: "REPEATABLE_READ"
transaction:
mode: "FULL_XA"
locking: "OPTIMISTIC"
expiration:
lifespan: "5000"
maxIdle: "1000"
memory:
maxCount: "1000000"
whenFull: "REMOVE"
indexing:
enabled: "true"
storage: "local-heap"
indexReader:
refreshInterval: "1000"
indexedEntities:
- "org.infinispan.Person"
partitionHandling:
whenSplit: "ALLOW_READ_WRITES"
mergePolicy: "PREFERRED_NON_NULL"
persistence:
passivation: "false"
# Persistent storage configuration.
Multiple caches
XML
<infinispan
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:infinispan:config:14.0 https://infinispan.org/schemas/infinispan-config-14.0.xsd
urn:infinispan:server:14.0 https://infinispan.org/schemas/infinispan-server-14.0.xsd"
xmlns="urn:infinispan:config:14.0"
xmlns:server="urn:infinispan:server:14.0">
<cache-container name="default"
statistics="true">
<distributed-cache name="mycacheone"
mode="ASYNC"
statistics="true">
<encoding media-type="application/x-protostream"/>
<expiration lifespan="300000"/>
<memory max-size="400MB"
when-full="REMOVE"/>
</distributed-cache>
<distributed-cache name="mycachetwo"
mode="SYNC"
statistics="true">
<encoding media-type="application/x-protostream"/>
<expiration lifespan="300000"/>
<memory max-size="400MB"
when-full="REMOVE"/>
</distributed-cache>
</cache-container>
</infinispan>
YAML
infinispan:
cacheContainer:
name: "default"
statistics: "true"
caches:
mycacheone:
distributedCache:
mode: "ASYNC"
statistics: "true"
encoding:
mediaType: "application/x-protostream"
expiration:
lifespan: "300000"
memory:
maxSize: "400MB"
whenFull: "REMOVE"
mycachetwo:
distributedCache:
mode: "SYNC"
statistics: "true"
encoding:
mediaType: "application/x-protostream"
expiration:
lifespan: "300000"
memory:
maxSize: "400MB"
whenFull: "REMOVE"
JSON
{
"infinispan" : {
"cache-container" : {
"name" : "default",
"statistics" : "true",
"caches" : {
"mycacheone" : {
"distributed-cache" : {
"mode": "ASYNC",
"statistics": "true",
"encoding": {
"media-type": "application/x-protostream"
},
"expiration" : {
"lifespan" : "300000"
},
"memory": {
"max-size": "400MB",
"when-full": "REMOVE"
}
}
},
"mycachetwo" : {
"distributed-cache" : {
"mode": "SYNC",
"statistics": "true",
"encoding": {
"media-type": "application/x-protostream"
},
"expiration" : {
"lifespan" : "300000"
},
"memory": {
"max-size": "400MB",
"when-full": "REMOVE"
}
}
}
}
}
}
}
Additional resources
2.1.2. Modifying Caches
Make changes to attributes in cache configurations across Data Grid clusters with PUT requests that include XML or JSON configuration in the payload.
You can modify a cache only if the changes are compatible with the existing configuration.
For example you cannot use a replicated cache configuration to modify a distributed cache. Likewise if you create a cache configuration with a specific attribute, you cannot modify the configuration to use a different attribute instead. For example, attempting to modify cache configuration by specifying a value for the max-count attribute results in invalid configuration if the max-size is already set.
PUT /rest/v2/caches/{cacheName}Table 2.2. Headers
| Header | Required or Optional | Parameter |
|---|---|---|
|
| REQUIRED |
Sets the MediaType for the Data Grid configuration payload; either |
|
| OPTIONAL | Used to set AdminFlags |
2.1.3. Verifying Caches
Check if caches are available in Data Grid clusters with HEAD requests.
HEAD /rest/v2/caches/{cacheName}2.1.4. Creating Caches with Templates
Create caches from Data Grid templates with POST requests and the ?template= parameter.
POST /rest/v2/caches/{cacheName}?template={templateName}2.1.5. Retrieving Cache Configuration
Retrieve Data Grid cache configurations with GET requests.
GET /rest/v2/caches/{name}?action=configTable 2.3. Headers
| Header | Required or Optional | Parameter |
|---|---|---|
|
| OPTIONAL |
Sets the required format to return content. Supported formats are |
2.1.6. Converting Cache Configurations between XML, JSON and YAML
Invoke a POST request with valid configuration and the ?action=convert parameter. Data Grid responds with the equivalent representation of the configuration in the type specified by the Accept header.
POST /rest/v2/caches?action=convert
To convert cache configuration you must specify the input format for the configuration with the Content-Type header and the desired output format with the Accept header. For example, the following command converts the replicated cache configuration from XML to YAML:
curl localhost:11222/rest/v2/caches?action=convert \ --digest -u username:password \ -X POST -H "Accept: application/yaml" -H "Content-Type: application/xml" \ -d '<replicated-cache mode="SYNC" statistics="false"><encoding media-type="application/x-protostream"/><expiration lifespan="300000" /><memory max-size="400MB" when-full="REMOVE"/></replicated-cache>'
2.1.7. Comparing Cache Configurations
Invoke a POST request with a multipart/form-data body containing two cache configurations and the ?action=compare parameter.
POST /rest/v2/caches?action=compare
Add the ignoreMutable=true parameter to ignore mutable attributes in the comparison.
Data Grid responds with 204 (No Content) in case the configurations are equal, and 409 (Conflict) in case they are different.
2.1.8. Retrieving All Cache Details
Invoke a GET request to retrieve all details for Data Grid caches.
GET /rest/v2/caches/{name}?action=statsData Grid provides a JSON response such as the following:
{
"stats": {
"time_since_start": -1,
"time_since_reset": -1,
"hits": -1,
"current_number_of_entries": -1,
"current_number_of_entries_in_memory": -1,
"total_number_of_entries": -1,
"stores": -1,
"off_heap_memory_used": -1,
"data_memory_used": -1,
"retrievals": -1,
"misses": -1,
"remove_hits": -1,
"remove_misses": -1,
"evictions": -1,
"average_read_time": -1,
"average_read_time_nanos": -1,
"average_write_time": -1,
"average_write_time_nanos": -1,
"average_remove_time": -1,
"average_remove_time_nanos": -1,
"required_minimum_number_of_nodes": -1
},
"size": 0,
"configuration": {
"distributed-cache": {
"mode": "SYNC",
"transaction": {
"stop-timeout": 0,
"mode": "NONE"
}
}
},
"rehash_in_progress": false,
"rebalancing_enabled": true,
"bounded": false,
"indexed": false,
"persistent": false,
"transactional": false,
"secured": false,
"has_remote_backup": false,
"indexing_in_progress": false,
"statistics": false
}-
statscurrent stats of the cache. -
sizethe estimated size for the cache. -
configurationthe cache configuration. -
rehash_in_progresstrue when a rehashing is in progress. -
indexing_in_progresstrue when indexing is in progress. -
rebalancing_enabledis true if rebalancing is enabled. Fetching this property might fail on the server. In that case the property won’t be present in the payload. -
boundedwhen expiration is enabled. -
indexedtrue if the cache is indexed. -
persistenttrue if the cache is persisted. -
transactionaltrue if the cache is transactional. -
securedtrue if the cache is secured. -
has_remote_backuptrue if the cache has remote backups. -
key_storagethe media type of the cache keys. -
value_storagethe media type of the cache values.
key_storage and value_storage matches encoding configuration of the cache. For server caches with no encoding, Data Grid assumes application/x-protostream when a cache is indexed and application/unknown otherwise.
2.1.9. Retrieving Data Distribution of a Cache
Invoke a GET request to retrieve all details for data distribution of Data Grid caches.
GET /rest/v2/caches/{name}?action=distributionData Grid provides a JSON response such as the following:
[
{
"node_name": "NodeA",
"node_addresses": [
"127.0.0.1:44175"
],
"memory_entries": 0,
"total_entries": 0,
"memory_used": 528512
},
{
"node_name":"NodeB",
"node_addresses": [
"127.0.0.1:44187"
],
"memory_entries": 0,
"total_entries": 0,
"memory_used": 528512
}
]Each element in the list represents a node. The properties are:
-
node_nameis the node name -
node_addressesis a list with all the node’s physical addresses. -
memory_entriesthe number of entries the node holds in memory belonging to the cache. -
total_entriesthe number of entries the node has in memory and disk belonging to the cache. -
memory_usedthe value in bytes the eviction algorithm estimates the cache occupies. Returns -1 if eviction is not enabled.
2.1.10. Retrieving all mutable cache configuration attributes
Invoke a GET request to retrieve all mutable cache configuration attributes for Data Grid caches.
GET /rest/v2/caches/{name}?action=get-mutable-attributesData Grid provides a JSON response such as the following:
[ "jmx-statistics.statistics", "locking.acquire-timeout", "transaction.single-phase-auto-commit", "expiration.max-idle", "transaction.stop-timeout", "clustering.remote-timeout", "expiration.lifespan", "expiration.interval", "memory.max-count", "memory.max-size" ]
Add the full parameter to obtain values and type information:
GET /rest/v2/caches/mycache?action=get-mutable-attributes&full=true
Data Grid provides a JSON response such as the following:
{
"jmx-statistics.statistics": {
"value": true,
"type": "boolean"
},
"locking.acquire-timeout": {
"value": 15000,
"type": "long"
},
"transaction.single-phase-auto-commit": {
"value": false,
"type": "boolean"
},
"expiration.max-idle": {
"value": -1,
"type": "long"
},
"transaction.stop-timeout": {
"value": 30000,
"type": "long"
},
"clustering.remote-timeout": {
"value": 17500,
"type": "long"
},
"expiration.lifespan": {
"value": -1,
"type": "long"
},
"expiration.interval": {
"value": 60000,
"type": "long"
},
"memory.max-count": {
"value": -1,
"type": "long"
},
"memory.max-size": {
"value": null,
"type": "string"
}
}
For attributes of type enum, an additional universe property will contain the set of possible values.
2.1.11. Updating cache configuration attributes
Invoke a POST request to change a mutable cache configuration attribute.
POST /rest/v2/caches/{name}?action=set-mutable-attributes&attribute-name={attributeName}&attribute-value={attributeValue}2.1.12. Adding Entries
Add entries to caches with POST requests.
POST /rest/v2/caches/{cacheName}/{cacheKey}
The preceding request places the payload, or request body, in the cacheName cache with the cacheKey key. The request replaces any data that already exists and updates the Time-To-Live and Last-Modified values, if they apply.
If the entry is created successfully, the service returns 204 (No Content).
If a value already exists for the specified key, the POST request returns 409 (Conflict) and does not modify the value. To update values, you should use PUT requests. See Replacing Entries.
Table 2.4. Headers
| Header | Required or Optional | Parameter |
|---|---|---|
|
| OPTIONAL | Sets the content type for the key in the request. See Key-Content-Type for more information. |
|
| OPTIONAL | Sets the MediaType of the value for the key. |
|
| OPTIONAL | Sets the number of seconds before the entry is automatically deleted. If you do not set this parameter, Data Grid uses the default value from the configuration. If you set a negative value, the entry is never deleted. |
|
| OPTIONAL | Sets the number of seconds that entries can be idle. If a read or write operation does not occur for an entry after the maximum idle time elapses, the entry is automatically deleted. If you do not set this parameter, Data Grid uses the default value from the configuration. If you set a negative value, the entry is never deleted. |
|
| OPTIONAL | The flags used to add the entry. See Flag for more information. |
The flags header also applies to all other operations involving data manipulation on the cache,
If both timeToLiveSeconds and maxIdleTimeSeconds have a value of 0, Data Grid uses the default lifespan and maxIdle values from the configuration.
If only maxIdleTimeSeconds has a value of 0, Data Grid uses:
-
the default
maxIdlevalue from the configuration. -
the value for
timeToLiveSecondsthat you pass as a request parameter or a value of-1if you do not pass a value.
If only timeToLiveSeconds has a value of 0, Data Grid uses:
-
the default
lifespanvalue from the configuration. -
the value for
maxIdlethat you pass as a request parameter or a value of-1if you do not pass a value.
2.1.13. Replacing Entries
Replace entries in caches with PUT requests.
PUT /rest/v2/caches/{cacheName}/{cacheKey}
If a value already exists for the specified key, the PUT request updates the value. If you do not want to modify existing values, use POST requests that return 409 (Conflict) instead of modifying values. See Adding Values.
2.1.14. Retrieving Data By Keys
Retrieve data for specific keys with GET requests.
GET /rest/v2/caches/{cacheName}/{cacheKey}
The server returns data from the given cache, cacheName, under the given key, cacheKey, in the response body. Responses contain Content-Type headers that correspond to the MediaType negotiation.
Browsers can also access caches directly, for example as a content delivery network (CDN). Data Grid returns a unique ETag for each entry along with the Last-Modified and Expires header fields.
These fields provide information about the state of the data that is returned in your request. ETags allow browsers and other clients to request only data that has changed, which conserves bandwidth.
Table 2.5. Headers
| Header | Required or Optional | Parameter |
|---|---|---|
|
| OPTIONAL |
Sets the content type for the key in the request. The default is |
|
| OPTIONAL | Sets the required format to return content. See Accept for more information. |
Append the extended parameter to the query string to get additional information:
GET /rest/v2/caches/{cacheName}/{cacheKey}?extendedThe preceding request returns custom headers:
-
Cluster-Primary-Ownerreturns the node name that is the primary owner of the key. -
Cluster-Node-Namereturns the JGroups node name of the server that handled the request. -
Cluster-Physical-Addressreturns the physical JGroups address of the server that handled the request.
2.1.15. Checking if Entries Exist
Verify that specific entries exists with HEAD requests.
HEAD /rest/v2/caches/{cacheName}/{cacheKey}The preceding request returns only the header fields and the same content that you stored with the entry. For example, if you stored a String, the request returns a String. If you stored binary, base64-encoded, blobs or serialized Java objects, Data Grid does not de-serialize the content in the request.
HEAD requests also support the extended parameter.
Table 2.6. Headers
| Header | Required or Optional | Parameter |
|---|---|---|
|
| OPTIONAL |
Sets the content type for the key in the request. The default is |
2.1.16. Deleting Entries
Remove entries from caches with DELETE requests.
DELETE /rest/v2/caches/{cacheName}/{cacheKey}Table 2.7. Headers
| Header | Required or Optional | Parameter |
|---|---|---|
|
| OPTIONAL |
Sets the content type for the key in the request. The default is |
2.1.17. Deleting Caches
Remove caches from Data Grid clusters with DELETE requests.
DELETE /rest/v2/caches/{cacheName}2.1.18. Retrieving All Keys from Caches
Invoke GET requests to retrieve all the keys in a cache in JSON format.
GET /rest/v2/caches/{cacheName}?action=keysTable 2.8. Request Parameters
| Parameter | Required or Optional | Value |
|---|---|---|
|
| OPTIONAL |
Specifies the maximum number of keys to retrieve using an InputStream. A negative value retrieves all keys. The default value is |
|
| OPTIONAL |
Specifies the internal batch size when retrieving the keys. The default value is |
2.1.19. Retrieving All Entries from Caches
Invoke GET requests to retrieve all the entries in a cache in JSON format.
GET /rest/v2/caches/{cacheName}?action=entriesTable 2.9. Request Parameters
| Parameter | Required or Optional | Value |
|---|---|---|
|
| OPTIONAL |
Includes metadata for each entry in the response. The default value is |
|
| OPTIONAL |
Specifies the maximum number of keys to include in the response. A negative value retrieves all keys. The default value is |
|
| OPTIONAL |
Specifies the internal batch size when retrieving the keys. The default value is |
|
| OPTIONAL |
If |
Data Grid provides a JSON response such as the following:
[
{
"key":1,
"value":"value1",
"timeToLiveSeconds":-1,
"maxIdleTimeSeconds":-1,
"created":-1,
"lastUsed":-1,
"expireTime":-1
},
{
"key":2,
"value":"value2",
"timeToLiveSeconds":10,
"maxIdleTimeSeconds":45,
"created":1607966017944,
"lastUsed": 1607966017944,
"expireTime":1607966027944
}
]-
keyThe key for the entry. -
valueThe value of the entry. -
timeToLiveSecondsBased on the entry lifespan but in seconds, or-1if the entry never expires. It’s not returned unless you set metadata="true". -
maxIdleTimeSecondsMaximum idle time, in seconds, or-1if entry never expires. It’s not returned unless you set metadata="true". -
createdTime the entry was created or or-1for immortal entries. It’s not returned unless you set metadata="true". -
lastUsedLast time an operation was performed on the entry or-1for immortal entries. It’s not returned unless you set metadata="true". -
expireTimeTime when the entry expires or-1for immortal entries. It’s not returned unless you set metadata="true".
2.1.20. Clearing Caches
To delete all data from a cache, invoke a POST request with the ?action=clear parameter.
POST /rest/v2/caches/{cacheName}?action=clear
If the operation successfully completes, the service returns 204 (No Content).
2.1.21. Getting Cache Size
Retrieve the size of caches across the entire cluster with GET requests and the ?action=size parameter.
GET /rest/v2/caches/{cacheName}?action=size2.1.22. Getting Cache Statistics
Obtain runtime statistics for caches with GET requests.
GET /rest/v2/caches/{cacheName}?action=stats2.1.23. Listing Caches
List all available caches in Data Grid clusters with GET requests.
GET /rest/v2/caches/
2.1.24. Listening to cache events
Receive cache events using Server-Sent Events. The event value will be one of cache-entry-created, cache-entry-removed, cache-entry-updated, cache-entry-expired. The data value will contain the key of the entry that has fired the event in the format set by the Accept header.
GET /rest/v2/caches/{name}?action=listenTable 2.10. Headers
| Header | Required or Optional | Parameter |
|---|---|---|
|
| OPTIONAL |
Sets the required format to return content. Supported formats are |
2.1.25. Enabling rebalancing
Turn on automatic rebalancing for a specific cache.
POST /rest/v2/caches/{cacheName}?action=enable-rebalancing2.1.26. Disabling rebalancing
Turn off automatic rebalancing for a specific cache.
POST /rest/v2/caches/{cacheName}?action=disable-rebalancing2.1.27. Getting Cache Availability
Retrieve the availability of a cache.
GET /rest/v2/caches/{cacheName}?action=get-availabilityYou can get the availability of internal caches but this is subject to change in future Data Grid versions.
2.1.28. Setting Cache Availability
Change the availability of clustered caches when using either the DENY_READ_WRITES or ALLOW_READS partition handling strategy.
POST /rest/v2/caches/{cacheName}?action=set-availability&availability={AVAILABILITY}Table 2.11. Request Parameters
| Parameter | Required or Optional | Value |
|---|---|---|
|
| REQUIRED | AVAILABLE or DEGRADED_MODE |
-
AVAILABLEmakes caches available to all nodes in a network partition. -
DEGRADED_MODEprevents read and write operations on caches when network partitions occur.
You can set the availability of internal caches but this is subject to change in future Data Grid versions.
2.1.29. Indexing and Querying with the REST API
Query remote caches with GET requests and the ?action=search&query parameter from any HTTP client.
GET /rest/v2/caches/{cacheName}?action=search&query={ickle query}Data Grid response
{
"total_results" : 150,
"hits" : [ {
"hit" : {
"name" : "user1",
"age" : 35
}
}, {
"hit" : {
"name" : "user2",
"age" : 42
}
}, {
"hit" : {
"name" : "user3",
"age" : 12
}
} ]
}
-
total_resultsdisplays the total number of results from the query. -
hitsis an array of matches from the query. hitis an object that matches the query.TipHits can contain all fields or a subset of fields if you use a
Selectclause.
Table 2.12. Request Parameters
| Parameter | Required or Optional | Value |
|---|---|---|
|
| REQUIRED | Specifies the query string. |
|
| OPTIONAL |
Sets the number of results to return. The default is |
|
| OPTIONAL |
Specifies the index of the first result to return. The default is |
|
| OPTIONAL |
When |
To use the body of the request instead of specifying query parameters, invoke POST requests as follows:
POST /rest/v2/caches/{cacheName}?action=searchQuery in request body
{
"query":"from Entity where name:\"user1\"",
"max_results":20,
"offset":10
}
2.1.29.1. Rebuilding indexes
When you delete fields or change index field definitions, you must rebuild the index to ensure the index is consistent with data in the cache.
Rebuilding Protobuf schema using REST, CLI, Data Grid Console or remote client might lead to inconsistencies. Remote clients might have different versions of the Protostream entity and this might lead to unreliable behavior.
Reindex all data in caches with POST requests and the ?action=reindex parameter.
POST /v2/caches/{cacheName}/search/indexes?action=reindexTable 2.13. Request Parameters
| Parameter | Required or Optional | Value |
|---|---|---|
|
| OPTIONAL |
Values for the
*
* |
|
| OPTIONAL |
When |
2.1.29.2. Updating index schema
The update index schema operation lets you add schema changes with a minimal downtime. Instead of removing previously indexed data and recreating the index schema, Data Grid adds new fields to the existing schema.
Update the index schema of values in your cache using POST requests and the ?action=updateSchema parameter.
POST /v2/caches/{cacheName}/search/indexes?action=updateSchema2.1.29.3. Purging indexes
Delete all indexes from caches with POST requests and the ?action=clear parameter.
POST /rest/v2/caches/{cacheName}/search/indexes?action=clear
If the operation successfully completes, the service returns 204 (No Content).
2.1.29.4. Get Indexes Metamodel
Present the full index schema metamodel of all indexes defined on this cache.
GET /rest/v2/caches/{cacheName}/search/indexes/metamodelData Grid response
[{
"entity-name": "org.infinispan.query.test.Book",
"java-class": "org.infinispan.query.test.Book",
"index-name": "org.infinispan.query.test.Book",
"value-fields": {
"description": {
"multi-valued": false,
"multi-valued-in-root": false,
"type": "java.lang.String",
"projection-type": "java.lang.String",
"argument-type": "java.lang.String",
"searchable": true,
"sortable": false,
"projectable": false,
"aggregable": false,
"analyzer": "standard"
},
"name": {
"multi-valued": false,
"multi-valued-in-root": true,
"type": "java.lang.String",
"projection-type": "java.lang.String",
"argument-type": "java.lang.String",
"searchable": true,
"sortable": false,
"projectable": false,
"aggregable": false,
"analyzer": "standard"
},
"surname": {
"multi-valued": false,
"multi-valued-in-root": true,
"type": "java.lang.String",
"projection-type": "java.lang.String",
"argument-type": "java.lang.String",
"searchable": true,
"sortable": false,
"projectable": false,
"aggregable": false
},
"title": {
"multi-valued": false,
"multi-valued-in-root": false,
"type": "java.lang.String",
"projection-type": "java.lang.String",
"argument-type": "java.lang.String",
"searchable": true,
"sortable": false,
"projectable": false,
"aggregable": false
}
},
"object-fields": {
"authors": {
"multi-valued": true,
"multi-valued-in-root": true,
"nested": true,
"value-fields": {
"name": {
"multi-valued": false,
"multi-valued-in-root": true,
"type": "java.lang.String",
"projection-type": "java.lang.String",
"argument-type": "java.lang.String",
"searchable": true,
"sortable": false,
"projectable": false,
"aggregable": false,
"analyzer": "standard"
},
"surname": {
"multi-valued": false,
"multi-valued-in-root": true,
"type": "java.lang.String",
"projection-type": "java.lang.String",
"argument-type": "java.lang.String",
"searchable": true,
"sortable": false,
"projectable": false,
"aggregable": false
}
}
}
}
}, {
"entity-name": "org.infinispan.query.test.Author",
"java-class": "org.infinispan.query.test.Author",
"index-name": "org.infinispan.query.test.Author",
"value-fields": {
"surname": {
"multi-valued": false,
"multi-valued-in-root": false,
"type": "java.lang.String",
"projection-type": "java.lang.String",
"argument-type": "java.lang.String",
"searchable": true,
"sortable": false,
"projectable": false,
"aggregable": false
},
"name": {
"multi-valued": false,
"multi-valued-in-root": false,
"type": "java.lang.String",
"projection-type": "java.lang.String",
"argument-type": "java.lang.String",
"searchable": true,
"sortable": false,
"projectable": false,
"aggregable": false,
"analyzer": "standard"
}
}
}]
2.1.29.5. Retrieving Query and Index Statistics
Obtain information about queries and indexes in caches with GET requests.
You must enable statistics in the cache configuration or results are empty.
GET /rest/v2/caches/{cacheName}/search/statsTable 2.14. Request Parameters
| Parameter | Required or Optional | Value |
|---|---|---|
|
| OPTIONAL |
Use |
Data Grid response
{
"query": {
"indexed_local": {
"count": 1,
"average": 12344.2,
"max": 122324,
"slowest": "FROM Entity WHERE field > 4"
},
"indexed_distributed": {
"count": 0,
"average": 0.0,
"max": -1,
"slowest": "FROM Entity WHERE field > 4"
},
"hybrid": {
"count": 0,
"average": 0.0,
"max": -1,
"slowest": "FROM Entity WHERE field > 4 AND desc = 'value'"
},
"non_indexed": {
"count": 0,
"average": 0.0,
"max": -1,
"slowest": "FROM Entity WHERE desc = 'value'"
},
"entity_load": {
"count": 123,
"average": 10.0,
"max": 120
}
},
"index": {
"types": {
"org.infinispan.same.test.Entity": {
"count": 5660001,
"size": 0
},
"org.infinispan.same.test.AnotherEntity": {
"count": 40,
"size": 345560
}
},
"reindexing": false
}
}
In the section:
query
-
indexed_localProvides details about indexed queries. -
indexed_distributedProvides details about distributed indexed queries. -
hybridProvides details about queries that used the index only partially. -
non_indexedProvides details about queries that didn’t use the index. -
entity_loadProvides details about cache operations to fetch objects after indexed queries execution.
Time is always measured in nanoseconds.
In the section:
index
typesProvide details about each indexed type (class name or protobuf message) that is configured in the cache.-
countThe number of entities indexed for the type. -
sizeUsage in bytes of the type.
-
-
reindexingIf the value istrue, theIndexeris running in the cache.
2.1.29.6. Clearing Query Statistics
Reset runtime statistics with POST requests and the ?action=clear parameter.
POST /rest/v2/caches/{cacheName}/search/stats?action=clearData Grid resets only query execution times for the local node only. This operation does not clear index statistics.
2.1.29.7. Retrieving Index Statistics (Deprecated)
Obtain information about indexes in caches with GET requests.
GET /rest/v2/caches/{cacheName}/search/indexes/statsData Grid response
{
"indexed_class_names": ["org.infinispan.sample.User"],
"indexed_entities_count": {
"org.infinispan.sample.User": 4
},
"index_sizes": {
"cacheName_protobuf": 14551
},
"reindexing": false
}
-
indexed_class_namesProvides the class names of the indexes present in the cache. For Protobuf the value is alwaysorg.infinispan.query.remote.impl.indexing.ProtobufValueWrapper. -
indexed_entities_countProvides the number of entities indexed per class. -
index_sizesProvides the size, in bytes, for each index in the cache. -
reindexingIndicates if a re-indexing operation was performed for the cache. If the value istrue, theMassIndexerwas started in the cache.
2.1.29.8. Retrieving Query Statistics (Deprecated)
Get information about the queries that have been run in caches with GET requests.
GET /rest/v2/caches/{cacheName}/search/query/statsData Grid response
{
"search_query_execution_count":20,
"search_query_total_time":5,
"search_query_execution_max_time":154,
"search_query_execution_avg_time":2,
"object_loading_total_time":1,
"object_loading_execution_max_time":1,
"object_loading_execution_avg_time":1,
"objects_loaded_count":20,
"search_query_execution_max_time_query_string": "FROM entity"
}
-
search_query_execution_countProvides the number of queries that have been run. -
search_query_total_timeProvides the total time spent on queries. -
search_query_execution_max_timeProvides the maximum time taken for a query. -
search_query_execution_avg_timeProvides the average query time. -
object_loading_total_timeProvides the total time spent loading objects from the cache after query execution. -
object_loading_execution_max_timeProvides the maximum time spent loading objects execution. -
object_loading_execution_avg_timeProvides the average time spent loading objects execution. -
objects_loaded_countProvides the count of objects loaded. -
search_query_execution_max_time_query_stringProvides the slowest query executed.
2.1.29.9. Clearing Query Statistics (Deprecated)
Reset runtime statistics with POST requests and the ?action=clear parameter.
POST /rest/v2/caches/{cacheName}/search/query/stats?action=clear2.1.30. Cross-Site Operations with Caches
Perform cross-site replication operations with the Data Grid REST API.
2.1.30.1. Getting status of all backup locations
Retrieve the status of all backup locations with GET requests.
GET /rest/v2/caches/{cacheName}/x-site/backups/Data Grid responds with the status of each backup location in JSON format, as in the following example:
{
"NYC": {
"status": "online"
},
"LON": {
"status": "mixed",
"online": [
"NodeA"
],
"offline": [
"NodeB"
]
}
}Table 2.15. Returned Status
| Value | Description |
|---|---|
|
| All nodes in the local cluster have a cross-site view with the backup location. |
|
| No nodes in the local cluster have a cross-site view with the backup location. |
|
| Some nodes in the local cluster have a cross-site view with the backup location, other nodes in the local cluster do not have a cross-site view. The response indicates status for each node. |
2.1.30.2. Getting status of specific backup locations
Retrieve the status of a backup location with GET requests.
GET /rest/v2/caches/{cacheName}/x-site/backups/{siteName}Data Grid responds with the status of each node in the site in JSON format, as in the following example:
{
"NodeA":"offline",
"NodeB":"online"
}Table 2.16. Returned Status
| Value | Description |
|---|---|
|
| The node is online. |
|
| The node is offline. |
|
| Not possible to retrieve status. The remote cache could be shutting down or a network error occurred during the request. |
2.1.30.3. Taking backup locations offline
Take backup locations offline with POST requests and the ?action=take-offline parameter.
POST /rest/v2/caches/{cacheName}/x-site/backups/{siteName}?action=take-offline2.1.30.4. Bringing backup locations online
Bring backup locations online with the ?action=bring-online parameter.
POST /rest/v2/caches/{cacheName}/x-site/backups/{siteName}?action=bring-online2.1.30.5. Pushing state to backup locations
Push cache state to a backup location with the ?action=start-push-state parameter.
POST /rest/v2/caches/{cacheName}/x-site/backups/{siteName}?action=start-push-state2.1.30.6. Canceling state transfer
Cancel state transfer operations with the ?action=cancel-push-state parameter.
POST /rest/v2/caches/{cacheName}/x-site/backups/{siteName}?action=cancel-push-state2.1.30.7. Getting state transfer status
Retrieve status of state transfer operations with the ?action=push-state-status parameter.
GET /rest/v2/caches/{cacheName}/x-site/backups?action=push-state-statusData Grid responds with the status of state transfer for each backup location in JSON format, as in the following example:
{
"NYC":"CANCELED",
"LON":"OK"
}Table 2.17. Returned status
| Value | Description |
|---|---|
|
| State transfer to the backup location is in progress. |
|
| State transfer completed successfully. |
|
| An error occurred with state transfer. Check log files. |
|
| State transfer cancellation is in progress. |
2.1.30.8. Clearing state transfer status
Clear state transfer status for sending sites with the ?action=clear-push-state-status parameter.
POST /rest/v2/caches/{cacheName}/x-site/local?action=clear-push-state-status2.1.30.9. Modifying take offline conditions
Sites go offline if certain conditions are met. Modify the take offline parameters to control when backup locations automatically go offline.
Procedure
Check configured take offline parameters with
GETrequests and thetake-offline-configparameter.GET /rest/v2/caches/{cacheName}/x-site/backups/{siteName}/take-offline-configThe Data Grid response includes
after_failuresandmin_waitfields as follows:{ "after_failures": 2, "min_wait": 1000 }Modify take offline parameters in the body of
PUTrequests.PUT /rest/v2/caches/{cacheName}/x-site/backups/{siteName}/take-offline-configIf the operation successfully completes, the service returns
204 (No Content).
2.1.30.10. Canceling state transfer from receiving sites
If the connection between two backup locations breaks, you can cancel state transfer on the site that is receiving the push.
Cancel state transfer from a remote site and keep the current state of the local cache with the ?action=cancel-receive-state parameter.
POST /rest/v2/caches/{cacheName}/x-site/backups/{siteName}?action=cancel-receive-state2.1.31. Rolling Upgrades
Perform rolling upgrades of cache data between Data Grid clusters
2.1.31.1. Connecting Source Clusters
Connect a target cluster to the source cluster with:
POST /rest/v2/caches/{cacheName}/rolling-upgrade/source-connection
You must provide a remote-store definition in JSON format as the body:
JSON
{
"remote-store": {
"cache": "my-cache",
"shared": true,
"raw-values": true,
"socket-timeout": 60000,
"protocol-version": "2.9",
"remote-server": [
{
"host": "127.0.0.2",
"port": 12222
}
],
"connection-pool": {
"max-active": 110,
"exhausted-action": "CREATE_NEW"
},
"async-executor": {
"properties": {
"name": 4
}
},
"security": {
"authentication": {
"server-name": "servername",
"digest": {
"username": "username",
"password": "password",
"realm": "realm",
"sasl-mechanism": "DIGEST-MD5"
}
},
"encryption": {
"protocol": "TLSv1.2",
"sni-hostname": "snihostname",
"keystore": {
"filename": "/path/to/keystore_client.jks",
"password": "secret",
"certificate-password": "secret",
"key-alias": "hotrod",
"type": "JKS"
},
"truststore": {
"filename": "/path/to/gca.jks",
"password": "secret",
"type": "JKS"
}
}
}
}
}
Several elements are optional such as security, async-executor and connection-pool. The configuration must contain minimally the cache name, the raw-values set to false and the host/ip of the single port in the source cluster. For details about the remote-store configuration, consult the XSD Schema.
If the operation successfully completes, the service returns 204 (No Content). If the target cluster is already connected to the source cluster, it returns status 304 (Not Modified).
2.1.31.2. Obtaining Source Cluster connection details
To obtain the remote-store definition of a cache, use a GET request:
GET /rest/v2/caches/{cacheName}/rolling-upgrade/source-connection
If the cache was previously connected, it returns the configuration of the associated remote-store in JSON format and status 200 (OK), otherwise a 404 (Not Found) status.
This is not a cluster wide operation, and it only returns the remote-store of the cache in the node where the REST invocation is handled.
2.1.31.3. Checking if a Cache is connected
To check if a cache have been connected to a remote cluster, use a HEAD request:
HEAD /rest/v2/caches/{cacheName}/rolling-upgrade/source-connection
Returns status 200 (OK) if for all nodes of the cluster, cacheName has a single remote store configured, and 404 (NOT_FOUND) otherwise.
2.1.31.4. Synchronizing Data
Synchronize data from a source cluster to a target cluster with POST requests and the ?action=sync-data parameter:
POST /rest/v2/caches/{cacheName}?action=sync-dataWhen the operation completes, Data Grid responds with the total number of entries copied to the target cluster.
2.1.31.5. Disconnecting Source Clusters
After you synchronize data to target clusters, disconnect from the source cluster with DELETE requests:
DELETE /rest/v2/caches/{cacheName}/rolling-upgrade/source-connection
If the operation successfully completes, the service returns 204 (No Content). It no source was connected, it returns code 304 (Not Modified).
2.2. Creating and Managing Counters
Create, delete, and modify counters via the REST API.
2.2.1. Creating Counters
Create counters with POST requests that include configuration in the payload.
POST /rest/v2/counters/{counterName}Example Weak Counter
{
"weak-counter":{
"initial-value":5,
"storage":"PERSISTENT",
"concurrency-level":1
}
}
Example Strong Counter
{
"strong-counter":{
"initial-value":3,
"storage":"PERSISTENT",
"upper-bound":5
}
}
2.2.2. Deleting Counters
Remove specific counters with DELETE requests.
DELETE /rest/v2/counters/{counterName}2.2.3. Retrieving Counter Configuration
Retrieve configuration for specific counters with GET requests.
GET /rest/v2/counters/{counterName}/configData Grid responds with the counter configuration in JSON format.
2.2.4. Getting Counter Values
Retrieve counter values with GET requests.
GET /rest/v2/counters/{counterName}Table 2.18. Headers
| Header | Required or Optional | Parameter |
|---|---|---|
| OPTIONAL | The required format to return the content. Supported formats are application/json and text/plain. JSON is assumed if no header is provided. |
2.2.5. Resetting Counters
Restore the initial value of counters without POST requests and the ?action=reset parameter.
POST /rest/v2/counters/{counterName}?action=reset
If the operation successfully completes, the service returns 204 (No Content).
2.2.6. Incrementing Counters
Increment counter values with POST request` and the ?action=increment parameter.
POST /rest/v2/counters/{counterName}?action=increment
WEAK counters never respond after operations and return 204 (No Content).
STRONG counters return 200 (OK) and the current value after each operation.
2.2.7. Adding Deltas to Counters
Add arbitrary values to counters with POST requests that include the ?action=add and delta parameters.
POST /rest/v2/counters/{counterName}?action=add&delta={delta}
WEAK counters never respond after operations and return 204 (No Content).
STRONG counters return 200 (OK) and the current value after each operation.
2.2.8. Decrementing Counter Values
Decrement counter values with POST requests and the ?action=decrement parameter.
POST /rest/v2/counters/{counterName}?action=decrement
WEAK counters never respond after operations and return 204 (No Content).
STRONG counters return 200 (OK) and the current value after each operation.
2.2.9. Performing compareAndSet Operations on Strong Counters
Atomically set values for strong counters with GET requests and the compareAndSet parameter.
POST /rest/v2/counters/{counterName}?action=compareAndSet&expect={expect}&update={update}
Data Grid atomically sets the value to {update} if the current value is {expect}. If the operation is successful, Data Grid returns true.
2.2.10. Performing compareAndSwap Operations on Strong Counters
Atomically set values for strong counters with GET requests and the compareAndSwap parameter.
POST /rest/v2/counters/{counterName}?action=compareAndSwap&expect={expect}&update={update}
Data Grid atomically sets the value to {update} if the current value is {expect}. If the operation is successful, Data Grid returns the previous value in the payload.
2.2.11. Listing Counters
Retrieve a list of counters in Data Grid clusters with GET requests.
GET /rest/v2/counters/
2.3. Working with Protobuf Schemas
Create and manage Protobuf schemas, .proto files, via the Data Grid REST API.
2.3.1. Creating Protobuf Schemas
Create Protobuf schemas across Data Grid clusters with POST requests that include the content of a protobuf file in the payload.
POST /rest/v2/schemas/{schemaName}
If the schema already exists, Data Grid returns HTTP 409 (Conflict). If the schema is not valid, either because of syntax errors, or because some of its dependencies are missing, Data Grid stores the schema and returns the error in the response body.
Data Grid responds with the schema name and any errors.
{
"name" : "users.proto",
"error" : {
"message": "Schema users.proto has errors",
"cause": "java.lang.IllegalStateException:Syntax error in error.proto at 3:8: unexpected label: messoge"
}
}-
nameis the name of the Protobuf schema. -
errorisnullfor valid Protobuf schemas. If Data Grid cannot successfully validate the schema, it returns errors.
If the operation successfully completes, the service returns 201 (Created).
2.3.2. Reading Protobuf Schemas
Retrieve Protobuf schema from Data Grid with GET requests.
GET /rest/v2/schemas/{schemaName}2.3.3. Updating Protobuf Schemas
Modify Protobuf schemas with PUT requests that include the content of a protobuf file in the payload.
When you make changes to the existing Protobuf schema definition, you must either update or rebuild the index schema. If the changes involve modifying the existing fields, then you must rebuild the index. When you add new fields without touching existing schema, you can update the index schema instead of rebuilding it.
PUT /rest/v2/schemas/{schemaName}If the schema is not valid, either because of syntax errors, or because some of its dependencies are missing, Data Grid updates the schema and returns the error in the response body.
{
"name" : "users.proto",
"error" : {
"message": "Schema users.proto has errors",
"cause": "java.lang.IllegalStateException:Syntax error in error.proto at 3:8: unexpected label: messoge"
}
}-
nameis the name of the Protobuf schema. -
errorisnullfor valid Protobuf schemas. If Data Grid cannot successfully validate the schema, it returns errors.
2.3.4. Deleting Protobuf Schemas
Remove Protobuf schemas from Data Grid clusters with DELETE requests.
DELETE /rest/v2/schemas/{schemaName}
If the operation successfully completes, the service returns 204 (No Content).
2.3.5. Listing Protobuf Schemas
List all available Protobuf schemas with GET requests.
GET /rest/v2/schemas/
Data Grid responds with a list of all schemas available on the cluster.
[ {
"name" : "users.proto",
"error" : {
"message": "Schema users.proto has errors",
"cause": "java.lang.IllegalStateException:Syntax error in error.proto at 3:8: unexpected label: messoge"
}
}, {
"name" : "people.proto",
"error" : null
}]-
nameis the name of the Protobuf schema. -
errorisnullfor valid Protobuf schemas. If Data Grid cannot successfully validate the schema, it returns errors.
2.3.6. Listing Protobuf Types
List all available Protobuf types with GET requests.
GET /rest/v2/schemas?action=types
Data Grid responds with a list of all types available on the cluster.
["org.infinispan.Person", "org.infinispan.Phone"]
2.4. Working with Cache Managers
Interact with Data Grid Cache Managers to get cluster and usage statistics.
2.4.1. Getting Basic Cache Manager Information
Retrieving information about Cache Managers with GET requests.
GET /rest/v2/cache-managers/{cacheManagerName}Data Grid responds with information in JSON format, as in the following example:
{
"version":"xx.x.x-FINAL",
"name":"default",
"coordinator":true,
"cache_configuration_names":[
"___protobuf_metadata",
"cache2",
"CacheManagerResourceTest",
"cache1"
],
"cluster_name":"ISPN",
"physical_addresses":"[127.0.0.1:35770]",
"coordinator_address":"CacheManagerResourceTest-NodeA-49696",
"cache_manager_status":"RUNNING",
"created_cache_count":"3",
"running_cache_count":"3",
"node_address":"CacheManagerResourceTest-NodeA-49696",
"cluster_members":[
"CacheManagerResourceTest-NodeA-49696",
"CacheManagerResourceTest-NodeB-28120"
],
"cluster_members_physical_addresses":[
"127.0.0.1:35770",
"127.0.0.1:60031"
],
"cluster_size":2,
"defined_caches":[
{
"name":"CacheManagerResourceTest",
"started":true
},
{
"name":"cache1",
"started":true
},
{
"name":"___protobuf_metadata",
"started":true
},
{
"name":"cache2",
"started":true
}
],
"local_site": "LON",
"relay_node": true,
"relay_nodes_address": [
"CacheManagerResourceTest-NodeA-49696"
],
"sites_view": [
"LON",
"NYC"
],
"rebalancing_enabled": true
}-
versioncontains the Data Grid version -
namecontains the name of the Cache Manager as defined in the configuration -
coordinatoris true if the Cache Manager is the coordinator of the cluster -
cache_configuration_namescontains an array of all caches configurations defined in the Cache Manager -
cluster_namecontains the name of the cluster as defined in the configuration -
physical_addressescontains the physical network addresses associated with the Cache Manager -
coordinator_addresscontains the physical network addresses of the coordinator of the cluster -
cache_manager_statusthe lifecycle status of the Cache Manager. For possible values, check theorg.infinispan.lifecycle.ComponentStatusdocumentation -
created_cache_countnumber of created caches, excludes all internal and private caches -
running_cache_countnumber of created caches that are running -
node_addresscontains the logical address of the Cache Manager -
cluster_membersandcluster_members_physical_addressesan array of logical and physical addresses of the members of the cluster -
cluster_sizenumber of members in the cluster -
defined_cachesA list of all caches defined in the Cache Manager, excluding private caches but including internal caches that are accessible -
local_siteThe name of the local site.
If cross-site replication is not configured, Data Grid returns "local". -
relay_nodeis true if the node handles RELAY messages between clusters. -
relay_nodes_addressis an array of logical addresses for relay nodes. -
sites_viewThe list of sites that participate in cross-site replication.
If cross-site replication is not configured, Data Grid returns an empty list. -
rebalancing_enabledis true if rebalancing is enabled. Fetching this property might fail on the server. In that case the property won’t be present in the payload.
2.4.2. Getting Cluster Health
Retrieve health information for Data Grid clusters with GET requests.
GET /rest/v2/cache-managers/{cacheManagerName}/healthData Grid responds with cluster health information in JSON format, as in the following example:
{
"cluster_health":{
"cluster_name":"ISPN",
"health_status":"HEALTHY",
"number_of_nodes":2,
"node_names":[
"NodeA-36229",
"NodeB-28703"
]
},
"cache_health":[
{
"status":"HEALTHY",
"cache_name":"___protobuf_metadata"
},
{
"status":"HEALTHY",
"cache_name":"cache2"
},
{
"status":"HEALTHY",
"cache_name":"mycache"
},
{
"status":"HEALTHY",
"cache_name":"cache1"
}
]
}cluster_healthcontains the health of the cluster-
cluster_namespecifies the name of the cluster as defined in the configuration. health_statusprovides one of the following:-
DEGRADEDindicates at least one of the caches is in degraded mode. -
HEALTHY_REBALANCINGindicates at least one cache is in the rebalancing state. -
HEALTHYindicates all cache instances in the cluster are operating as expected. -
FAILEDindicates the cache failed to start with the provided configuration.
-
-
number_of_nodesdisplays the total number of cluster members. Returns a value of0for non-clustered (standalone) servers. -
node_namesis an array of all cluster members. Empty for standalone servers.
-
cache_healthcontains health information per-cache-
statusHEALTHY, DEGRADED, HEALTHY_REBALANCING or FAILED -
cache_namethe name of the cache as defined in the configuration.
-
2.4.3. Getting Cache Manager Health Status
Retrieve the health status of Cache Managers with GET requests that do not require authentication.
GET /rest/v2/cache-managers/{cacheManagerName}/health/status
Data Grid responds with one of the following in text/plain format:
-
HEALTHY -
HEALTHY_REBALANCING -
DEGRADED -
FAILED
2.4.4. Checking REST Endpoint Availability
Verify Data Grid server REST endpoint availability with HEAD requests.
HEAD /rest/v2/cache-managers/{cacheManagerName}/healthIf you receive a successful response code then the Data Grid REST server is running and serving requests.
2.4.5. Obtaining Global Configuration for Cache Managers
Retrieve global configuration for Cache Managers with GET requests.
GET /rest/v2/cache-managers/{cacheManagerName}/configTable 2.19. Headers
| Header | Required or Optional | Parameter |
|---|---|---|
| OPTIONAL | The required format to return the content. Supported formats are application/json and application/xml. JSON is assumed if no header is provided. |
Table 2.20. Request parameters
| Parameter | Required or Optional | Description |
|---|---|---|
|
| OPTIONAL |
If |
Reference
2.4.6. Obtaining Configuration for All Caches
Retrieve the configuration for all caches with GET requests.
GET /rest/v2/cache-managers/{cacheManagerName}/cache-configs
Data Grid responds with JSON arrays that contain each cache and cache configuration, as in the following example:
[
{
"name":"cache1",
"configuration":{
"distributed-cache":{
"mode":"SYNC",
"partition-handling":{
"when-split":"DENY_READ_WRITES"
},
"statistics":true
}
}
},
{
"name":"cache2",
"configuration":{
"distributed-cache":{
"mode":"SYNC",
"transaction":{
"mode":"NONE"
}
}
}
}
]Table 2.21. Request parameters
| Parameter | Required or Optional | Description |
|---|---|---|
|
| OPTIONAL |
If |
2.4.7. Listing Available Cache Templates
Retrieve all available Data Grid cache templates with GET requests.
GET /rest/v2/cache-managers/{cacheManagerName}/cache-configs/templatesTable 2.22. Request parameters
| Parameter | Required or Optional | Description |
|---|---|---|
|
| OPTIONAL |
If |
2.4.8. Obtaining Cache Status and Information
Retrieve a list of all available caches for a Cache Manager, along with cache statuses and details, with GET requests.
GET /rest/v2/cache-managers/{cacheManagerName}/cachesData Grid responds with JSON arrays that lists and describes each available cache, as in the following example:
[ {
"status" : "RUNNING",
"name" : "cache1",
"type" : "local-cache",
"simple_cache" : false,
"transactional" : false,
"persistent" : false,
"bounded": false,
"secured": false,
"indexed": true,
"has_remote_backup": true,
"health":"HEALTHY",
"rebalancing_enabled": true
}, {
"status" : "RUNNING",
"name" : "cache2",
"type" : "distributed-cache",
"simple_cache" : false,
"transactional" : true,
"persistent" : false,
"bounded": false,
"secured": false,
"indexed": true,
"has_remote_backup": true,
"health":"HEALTHY",
"rebalancing_enabled": false
}]Table 2.23. Request parameters
| Parameter | Required or Optional | Description |
|---|---|---|
|
| OPTIONAL |
If |
2.4.9. Getting Cache Manager Statistics
Retrieve the statistics for Cache Managers with GET requests.
GET /rest/v2/cache-managers/{cacheManagerName}/statsData Grid responds with Cache Manager statistics in JSON format, as in the following example:
{
"statistics_enabled":true,
"read_write_ratio":0.0,
"time_since_start":1,
"time_since_reset":1,
"number_of_entries":0,
"total_number_of_entries":0,
"off_heap_memory_used":0,
"data_memory_used":0,
"misses":0,
"remove_hits":0,
"remove_misses":0,
"evictions":0,
"average_read_time":0,
"average_read_time_nanos":0,
"average_write_time":0,
"average_write_time_nanos":0,
"average_remove_time":0,
"average_remove_time_nanos":0,
"required_minimum_number_of_nodes":1,
"hits":0,
"stores":0,
"current_number_of_entries_in_memory":0,
"hit_ratio":0.0,
"retrievals":0
}-
statistics_enabledistrueif statistics collection is enabled for the Cache Manager. -
read_write_ratiodisplays the read/write ratio across all caches. -
time_since_startshows the time, in seconds, since the Cache Manager started. -
time_since_resetshows the number of seconds since the Cache Manager statistics were last reset. -
number_of_entriesshows the total number of entries currently in all caches from the Cache Manager. This statistic returns entries in the local cache instances only. -
total_number_of_entriesshows the number of store operations performed across all caches for the Cache Manager. -
off_heap_memory_usedshows the amount, inbytes[], of off-heap memory used by this cache container. -
data_memory_usedshows the amount, inbytes[], that the current eviction algorithm estimates is in use for data across all caches. Returns0if eviction is not enabled. -
missesshows the number ofget()misses across all caches. -
remove_hitsshows the number of removal hits across all caches. -
remove_missesshows the number of removal misses across all caches. -
evictionsshows the number of evictions across all caches. -
average_read_timeshows the average number of milliseconds taken forget()operations across all caches. -
average_read_time_nanossame asaverage_read_timebut in nanoseconds. -
average_remove_timeshows the average number of milliseconds forremove()operations across all caches. -
average_remove_time_nanossame asaverage_remove_timebut in nanoseconds. -
required_minimum_number_of_nodesshows the required minimum number of nodes to guarantee data consistency. -
hitsprovides the number ofget()hits across all caches. -
storesprovides the number ofput()operations across all caches. -
current_number_of_entries_in_memoryshows the total number of entries currently in all caches, excluding passivated entries. -
hit_ratioprovides the total percentage hit/(hit+miss) ratio for all caches. -
retrievalsshows the total number ofget()operations.
2.4.10. Shutdown all container caches
Shut down the Data Grid container on the server with POST requests.
POST /rest/v2/container?action=shutdown
Data Grid responds with 204 (No Content) and then shutdowns all caches in the container. The servers remain running with active endpoints and clustering, however REST calls to container resources will result in a 503 Service Unavailable response.
This method is primarily intended for use by the Data Grid Operator. The expectation is that the Server processes will be manually terminated shortly after this endpoint is invoked. Once this method has been called, it’s not possible to restart the container state.
2.4.11. Enabling rebalancing for all caches
Turn on automatic rebalancing for all caches.
POST /rest/v2/cache-managers/{cacheManagerName}?action=enable-rebalancing2.4.12. Disabling rebalancing for all caches
Turn off automatic rebalancing for all caches.
POST /rest/v2/cache-managers/{cacheManagerName}?action=disable-rebalancing2.4.13. Backing Up Data Grid Cache Managers
Create backup archives, application/zip, that contain resources (caches, cache templates, counters, Protobuf schemas, server tasks, and so on) currently stored in the Cache Manager.
POST /rest/v2/cache-managers/{cacheManagerName}/backups/{backupName}
If a backup with the same name already exists, the service responds with 409 (Conflict). If the directory parameter is not valid, the service returns 400 (Bad Request). A 202 response indicates that the backup request is accepted for processing.
Optionally include a JSON payload with your request that contains parameters for the backup operation, as follows:
Table 2.24. JSON Parameters
| Key | Required or Optional | Value |
|---|---|---|
|
| OPTIONAL | Specifies a location on the server to create and store the backup archive. |
|
| OPTIONAL | Specifies the resources to back up, in JSON format. The default is to back up all resources. If you specify one or more resources, then Data Grid backs up only those resources. See the Resource Parameters table for more information. |
Table 2.25. Resource Parameters
| Key | Required or Optional | Value |
|---|---|---|
|
| OPTIONAL |
Specifies either an array of cache names to back up or |
|
| OPTIONAL |
Specifies either an array of cache templates to back up or |
|
| OPTIONAL |
Defines either an array of counter names to back up or |
|
| OPTIONAL |
Defines either an array of Protobuf schema names to back up or |
|
| OPTIONAL |
Specifies either an array of server tasks to back up or |
The following example creates a backup archive with all counters and caches named [cache1,cache2] in a specified directory:
{
"directory": "/path/accessible/to/the/server",
"resources": {
"caches": ["cache1", "cache2"],
"counters": ["*"]
}
}2.4.14. Listing Backups
Retrieve the names of all backup operations that are in progress, completed, or failed.
GET /rest/v2/cache-managers/{cacheManagerName}/backupsData Grid responds with an Array of all backup names as in the following example:
["backup1", "backup2"]
2.4.15. Checking Backup Availability
Verify that a backup operation is complete.
HEAD /rest/v2/cache-managers/{cacheManagerName}/backups/{backupName}
A 200 response indicates the backup archive is available. A 202 response indicates the backup operation is in progress.
2.4.16. Downloading Backup Archives
Download backup archives from the server.
GET /rest/v2/cache-managers/{cacheManagerName}/backups/{backupName}
A 200 response indicates the backup archive is available. A 202 response indicates the backup operation is in progress.
2.4.17. Deleting Backup Archives
Remove backup archives from the server.
DELETE /rest/v2/cache-managers/{cacheManagerName}/backups/{backupName}
A 204 response indicates that the backup archive is deleted. A 202 response indicates that the backup operation is in progress but will be deleted when the operation completes.
2.4.18. Restoring Data Grid Resources from Backup Archives
Restore Data Grid resources from backup archives. The provided {restoreName} is for tracking restore progress, and is independent of the name of backup file being restored.
You can restore resources only if the container name in the backup archive matches {cacheManagerName}.
POST /rest/v2/cache-managers/{cacheManagerName}/restores/{restoreName}
A 202 response indicates that the restore request has been accepted for processing.
2.4.18.1. Restoring from Backup Archives on Data Grid Server
Use the application/json content type with your POST request to back up from an archive that is available on the server.
Table 2.26. JSON Parameters
| Key | Required or Optional | Value |
|---|---|---|
|
| REQUIRED | Specifies the path of the backup archive to restore. |
|
| OPTIONAL | Specifies the resources to restore, in JSON format. The default is to restore all resources. If you specify one or more resources, then Data Grid restores only those resources. See the Resource Parameters table for more information. |
Table 2.27. Resource Parameters
| Key | Required or Optional | Value |
|---|---|---|
|
| OPTIONAL |
Specifies either an array of cache names to back up or |
|
| OPTIONAL |
Specifies either an array of cache templates to back up or |
|
| OPTIONAL |
Defines either an array of counter names to back up or |
|
| OPTIONAL |
Defines either an array of Protobuf schema names to back up or |
|
| OPTIONAL |
Specifies either an array of server tasks to back up or |
The following example restores all counters from a backup archive on the server:
{
"location": "/path/accessible/to/the/server/backup-to-restore.zip",
"resources": {
"counters": ["*"]
}
}2.4.18.2. Restoring from Local Backup Archives
Use the multipart/form-data content type with your POST request to upload a local backup archive to the server.
Table 2.28. Form Data
| Parameter | Content-Type | Required or Optional | Value |
|---|---|---|---|
|
|
| REQUIRED | Specifies the bytes of the backup archive to restore. |
|
|
| OPTIONAL | Defines a JSON object of request parameters. |
Example Request
Content-Type: multipart/form-data; boundary=5ec9bc07-f069-4662-a535-46069afeda32
Content-Length: 7721
--5ec9bc07-f069-4662-a535-46069afeda32
Content-Disposition: form-data; name="resources"
Content-Length: 23
{"scripts":["test.js"]}
--5ec9bc07-f069-4662-a535-46069afeda32
Content-Disposition: form-data; name="backup"; filename="testManagerRestoreParameters.zip"
Content-Type: application/zip
Content-Length: 7353
<zip-bytes>
--5ec9bc07-f069-4662-a535-46069afeda32--
2.4.19. Listing Restores
Retrieve the names of all restore requests that are in progress, completed, or failed.
GET /rest/v2/cache-managers/{cacheManagerName}/restoresData Grid responds with an Array of all restore names as in the following example:
["restore1", "restore2"]
2.4.20. Checking Restore Progress
Verify that a restore operation is complete.
HEAD /rest/v2/cache-managers/{cacheManagerName}/restores/{restoreName}
A 201 (Created) response indicates the restore operation is completed. A 202 (Accepted) response indicates the backup operation is in progress.
2.4.21. Deleting Restore Metadata
Remove metadata for restore requests from the server. This action removes all metadata associated with restore requests but does not delete any restored content. If you delete the request metadata, you can use the request name to perform subsequent restore operations.
DELETE /rest/v2/cache-managers/{cacheManagerName}/restores/{restoreName}
A 204 (No Content) response indicates that the restore metadata is deleted. A 202 (Accepted) response indicates that the restore operation is in progress and will be deleted when the operation completes.
2.4.22. Listening to container configuration events
Receive events about configuration changes using Server-Sent Events. The event value will be one of create-cache, remove-cache, update-cache, create-template, remove-template or update-template. The data value will contain the declarative configuration of the entity that has been created. Remove events will only contain the name of the removed entity.
GET /rest/v2/container/config?action=listen
Table 2.29. Headers
| Header | Required or Optional | Parameter |
|---|---|---|
|
| OPTIONAL |
Sets the required format to return content. Supported formats are |
Table 2.30. Request parameters
| Parameter | Required or Optional | Description |
|---|---|---|
|
| OPTIONAL |
If |
|
| OPTIONAL |
If |
2.4.23. Listening to container events
Receive events from the container using Server-Sent Events. The emitted events come from logged information, so each event contains an identifier associated with the message. The event value will be lifecycle-event. The data has the logged information, which includes the message, category, level, timestamp, owner, context, and scope, some of which may be empty. Currently, we expose only LIFECYCLE events.
GET /rest/v2/container?action=listen
Table 2.31. Headers
| Header | Required or Optional | Parameter |
|---|---|---|
|
| OPTIONAL |
Sets the required format to return content. Supported formats are |
Table 2.32. Request parameters
| Parameter | Required or Optional | Description |
|---|---|---|
|
| OPTIONAL |
If |
|
| OPTIONAL |
If |
2.4.24. Cross-Site Operations with Cache Managers
Perform cross-site operations with Cache Managers to apply the operations to all caches.
2.4.24.1. Getting status of backup locations
Retrieve the status of all backup locations from Cache Managers with GET requests.
GET /rest/v2/cache-managers/{cacheManagerName}/x-site/backups/Data Grid responds with status in JSON format, as in the following example:
{
"SFO-3":{
"status":"online"
},
"NYC-2":{
"status":"mixed",
"online":[
"CACHE_1"
],
"offline":[
"CACHE_2"
],
"mixed": [
"CACHE_3"
]
}
}Table 2.33. Returned status
| Value | Description |
|---|---|
|
| All nodes in the local cluster have a cross-site view with the backup location. |
|
| No nodes in the local cluster have a cross-site view with the backup location. |
|
| Some nodes in the local cluster have a cross-site view with the backup location, other nodes in the local cluster do not have a cross-site view. The response indicates status for each node. |
GET /rest/v2/cache-managers/{cacheManagerName}/x-site/backups/{site}Returns the status for a single backup location.
2.4.24.2. Taking backup locations offline
Take backup locations offline with the ?action=take-offline parameter.
POST /rest/v2/cache-managers/{cacheManagerName}/x-site/backups/{siteName}?action=take-offline2.4.24.3. Bringing backup locations online
Bring backup locations online with the ?action=bring-online parameter.
POST /rest/v2/cache-managers/{cacheManagerName}/x-site/backups/{siteName}?action=bring-online2.4.24.4. Retrieving the state transfer mode
Check the state transfer mode with GET requests.
GET /rest/v2/caches/{cacheName}/x-site/backups/{site}/state-transfer-mode2.4.24.5. Setting the state transfer mode
Configure the state transfer mode with the ?action=set parameter.
POST /rest/v2/caches/{cacheName}/x-site/backups/{site}/state-transfer-mode?action=set&mode={mode}2.4.24.6. Starting state transfer
Push state of all caches to remote sites with the ?action=start-push-state parameter.
POST /rest/v2/cache-managers/{cacheManagerName}/x-site/backups/{siteName}?action=start-push-state2.4.24.7. Canceling state transfer
Cancel ongoing state transfer operations with the ?action=cancel-push-state parameter.
POST /rest/v2/cache-managers/{cacheManagerName}/x-site/backups/{siteName}?action=cancel-push-state2.5. Working with Data Grid Servers
Monitor and manage Data Grid server instances.
2.5.1. Retrieving Basic Server Information
View basic information about Data Grid Servers with GET requests.
GET /rest/v2/server
Data Grid responds with the server name, codename, and version in JSON format as in the following example:
{
"version":"Infinispan 'Codename' xx.x.x.Final"
}2.5.2. Getting Cache Managers
Retrieve lists of Cache Managers for Data Grid Servers with GET requests.
GET /rest/v2/server/cache-managers
Data Grid responds with an array of the Cache Manager names configured for the server.
Data Grid currently supports one Cache Manager per server only.
2.5.3. Adding Caches to Ignore Lists
Configure Data Grid to temporarily exclude specific caches from client requests. Send empty POST requests that include the names of the Cache Manager name and the cache.
POST /rest/v2/server/ignored-caches/{cache-manager}/{cache}
Data Grid responds with 204 (No Content) if the cache is successfully added to the ignore list or 404 (Not Found) if the cache or Cache Manager are not found.
Data Grid currently supports one Cache Manager per server only. For future compatibility you must provide the Cache Manager name in the requests.
2.5.4. Removing Caches from Ignore Lists
Remove caches from the ignore list with DELETE requests.
DELETE /rest/v2/server/ignored-caches/{cache-manager}/{cache}
Data Grid responds with 204 (No Content) if the cache is successfully removed from ignore list or 404 (Not Found) if the cache or Cache Manager are not found.
2.5.5. Confirming Ignored Caches
Confirm that caches are ignored with GET requests.
GET /rest/v2/server/ignored-caches/{cache-manager}2.5.6. Obtaining Server Configuration
Retrieve Data Grid Server configurations with GET requests.
GET /rest/v2/server/config
Data Grid responds with the configuration in JSON format, as follows:
{
"server":{
"interfaces":{
"interface":{
"name":"public",
"inet-address":{
"value":"127.0.0.1"
}
}
},
"socket-bindings":{
"port-offset":0,
"default-interface":"public",
"socket-binding":[
{
"name":"memcached",
"port":11221,
"interface":"memcached"
}
]
},
"security":{
"security-realms":{
"security-realm":{
"name":"default"
}
}
},
"endpoints":{
"socket-binding":"default",
"security-realm":"default",
"hotrod-connector":{
"name":"hotrod"
},
"rest-connector":{
"name":"rest"
}
}
}
}2.5.7. Getting Environment Variables
Retrieve all environment variables for Data Grid Servers with GET requests.
GET /rest/v2/server/env
2.5.8. Getting JVM Memory Details
Retrieve JVM memory usage information for Data Grid Servers with GET requests.
GET /rest/v2/server/memory
Data Grid responds with heap and non-heap memory statistics, direct memory usage, and information about memory pools and garbage collection in JSON format.
2.5.9. Getting JVM Heap Dumps
Generate JVM heap dumps for Data Grid Servers with POST requests.
POST /rest/v2/server/memory?action=heap-dump[&live=true|false]
Data Grid generates a heap dump file in HPROF format in the server data directory and responds with the full path of the file in JSON format.
2.5.10. Getting JVM Thread Dumps
Retrieve the current thread dump for the JVM with GET requests.
GET /rest/v2/server/threads
Data Grid responds with the current thread dump in text/plain format.
2.5.11. Getting Diagnostic Reports for Data Grid Servers
Retrieve aggregated reports for Data Grid Servers with GET requests.
GET /rest/v2/server/report
Data Grid responds with a tar.gz archive that contains an aggregated report with diagnostic information about both the Data Grid Server and the host. The report provides details about CPU, memory, open files, network sockets and routing, threads, in addition to configuration and log files.
2.5.12. Stopping Data Grid Servers
Stop Data Grid Servers with POST requests.
POST /rest/v2/server?action=stop
Data Grid responds with 204 (No Content) and then stops running.
2.6. Working with Data Grid Clusters
Monitor and perform administrative tasks on Data Grid clusters.
2.6.1. Stopping Data Grid Clusters
Shut down entire Data Grid clusters with POST requests.
POST /rest/v2/cluster?action=stop
Data Grid responds with 204 (No Content) and then performs an orderly shutdown of the entire cluster.
2.6.2. Stopping Specific Data Grid Servers in Clusters
Shut down one or more specific servers in Data Grid clusters with GET requests and the ?action=stop&server parameter.
POST /rest/v2/cluster?action=stop&server={server1_host}&server={server2_host}
Data Grid responds with 204 (No Content).
2.6.3. Backing Up Data Grid Clusters
Create backup archives, application/zip, that contain resources (caches, templates, counters, Protobuf schemas, server tasks, and so on) currently stored in the cache container for the cluster.
POST /rest/v2/cluster/backups/{backupName}Optionally include a JSON payload with your request that contains parameters for the backup operation, as follows:
Table 2.34. JSON Parameters
| Key | Required or Optional | Value |
|---|---|---|
|
| OPTIONAL | Specifies a location on the server to create and store the backup archive. |
If the backup operation successfully completes, the service returns 202 (Accepted). If a backup with the same name already exists, the service returns 409 (Conflict). If the directory parameter is not valid, the service returns 400 (Bad Request).
2.6.4. Listing Backups
Retrieve the names of all backup operations that are in progress, completed, or failed.
GET /rest/v2/cluster/backups
Data Grid responds with an Array of all backup names as in the following example:
["backup1", "backup2"]
2.6.5. Checking Backup Availability
Verify that a backup operation is complete. A 200 response indicates the backup archive is available. A 202 response indicates the backup operation is in progress.
HEAD /rest/v2/cluster/backups/{backupName}2.6.6. Downloading Backup Archives
Download backup archives from the server. A 200 response indicates the backup archive is available. A 202 response indicates the backup operation is in progress.
GET /rest/v2/cluster/backups/{backupName}2.6.7. Deleting Backup Archives
Remove backup archives from the server. A 204 response indicates that the backup archive is deleted. A 202 response indicates that the backup operation is in progress but will be deleted when the operation completes.
DELETE /rest/v2/cluster/backups/{backupName}2.6.8. Restoring Data Grid Cluster Resources
Apply resources in a backup archive to restore Data Grid clusters. The provided {restoreName} is for tracking restore progress, and is independent of the name of backup file being restored.
You can restore resources only if the container name in the backup archive matches the container name for the cluster.
POST /rest/v2/cluster/restores/{restoreName}
A 202 response indicates that the restore request is accepted for processing.
2.6.8.1. Restoring from Backup Archives on Data Grid Server
Use the application/json content type with your POST request to back up from an archive that is available on the server.
Table 2.35. JSON Parameters
| Key | Required or Optional | Value |
|---|---|---|
|
| REQUIRED | Specifies the path of the backup archive to restore. |
|
| OPTIONAL | Specifies the resources to restore, in JSON format. The default is to restore all resources. If you specify one or more resources, then Data Grid restores only those resources. See the Resource Parameters table for more information. |
Table 2.36. Resource Parameters
| Key | Required or Optional | Value |
|---|---|---|
|
| OPTIONAL |
Specifies either an array of cache names to back up or |
|
| OPTIONAL |
Specifies either an array of cache templates to back up or |
|
| OPTIONAL |
Defines either an array of counter names to back up or |
|
| OPTIONAL |
Defines either an array of Protobuf schema names to back up or |
|
| OPTIONAL |
Specifies either an array of server tasks to back up or |
The following example restores all counters from a backup archive on the server:
{
"location": "/path/accessible/to/the/server/backup-to-restore.zip",
"resources": {
"counters": ["*"]
}
}2.6.8.2. Restoring from Local Backup Archives
Use the multipart/form-data content type with your POST request to upload a local backup archive to the server.
Table 2.37. Form Data
| Parameter | Content-Type | Required or Optional | Value |
|---|---|---|---|
|
|
| REQUIRED | Specifies the bytes of the backup archive to restore. |
Example Request
Content-Type: multipart/form-data; boundary=5ec9bc07-f069-4662-a535-46069afeda32 Content-Length: 7798 --5ec9bc07-f069-4662-a535-46069afeda32 Content-Disposition: form-data; name="backup"; filename="testManagerRestoreParameters.zip" Content-Type: application/zip Content-Length: 7353 <zip-bytes> --5ec9bc07-f069-4662-a535-46069afeda32--
2.6.9. Listing Restores
Retrieve the names of all restore requests that are in progress, completed, or failed.
GET /rest/v2/cluster/restores
Data Grid responds with an Array of all restore names as in the following example:
["restore1", "restore2"]
2.6.10. Checking Restore Progress
Verify that a restore operation is complete.
HEAD /rest/v2/cluster/restores/{restoreName}
A 201 (Created) response indicates the restore operation is completed. A 202 response indicates the backup operation is in progress.
2.6.11. Deleting Restore Metadata
Remove metadata for restore requests from the server. This action removes all metadata associated with restore requests but does not delete any restored content. If you delete the request metadata, you can use the request name to perform subsequent restore operations.
DELETE /rest/v2/cluster/restores/{restoreName}
A 204 response indicates that the restore metadata is deleted. A 202 response indicates that the restore operation is in progress and will be deleted when the operation completes.
2.6.12. Checking Cluster Distribution
Retrieve the distribution details about all servers in the Data Grid cluster.
GET /rest/v2/cluster?action=distribution
Returns a JSON array of each Data Grid server statistics in the cluster with the format:
[
{
"node_name": "NodeA",
"node_addresses": [
"127.0.0.1:39313"
],
"memory_available": 466180016,
"memory_used": 56010832
},
{
"node_name": "NodeB",
"node_addresses": [
"127.0.0.1:47477"
],
"memory_available": 467548568,
"memory_used": 54642280
}
]Each element in the array represents an Data Grid node. If the statistics collection is disabled, information about memory usage values is -1. The properties are:
-
node_nameis the node name. -
node_addressesis a list with all the node’s physical addresses. -
memory_availablethe node available memory in bytes. -
memory_usedthe node used memory in bytes.
2.7. Data Grid Server logging configuration
View and modify the logging configuration on Data Grid clusters at runtime.
2.7.1. Listing the logging appenders
View a list of all configured appenders with GET requests.
GET /rest/v2/logging/appenders
Data Grid responds with a list of appenders in JSON format as in the following example:
{
"STDOUT" : {
"name" : "STDOUT"
},
"JSON-FILE" : {
"name" : "JSON-FILE"
},
"HR-ACCESS-FILE" : {
"name" : "HR-ACCESS-FILE"
},
"FILE" : {
"name" : "FILE"
},
"REST-ACCESS-FILE" : {
"name" : "REST-ACCESS-FILE"
}
}2.7.2. Listing the loggers
View a list of all configured loggers with GET requests.
GET /rest/v2/logging/loggers
Data Grid responds with a list of loggers in JSON format as in the following example:
[ {
"name" : "",
"level" : "INFO",
"appenders" : [ "STDOUT", "FILE" ]
}, {
"name" : "org.infinispan.HOTROD_ACCESS_LOG",
"level" : "INFO",
"appenders" : [ "HR-ACCESS-FILE" ]
}, {
"name" : "com.arjuna",
"level" : "WARN",
"appenders" : [ ]
}, {
"name" : "org.infinispan.REST_ACCESS_LOG",
"level" : "INFO",
"appenders" : [ "REST-ACCESS-FILE" ]
} ]2.7.3. Creating/modifying a logger
Create a new logger or modify an existing one with PUT requests.
PUT /rest/v2/logging/loggers/{loggerName}?level={level}&appender={appender}&appender={appender}...
Data Grid sets the level of the logger identified by {loggerName} to {level}. Optionally, it is possible to set one or more appenders for the logger. If no appenders are specified, those specified in the root logger will be used.
If the operation successfully completes, the service returns 204 (No Content).
2.7.4. Removing a logger
Remove an existing logger with DELETE requests.
DELETE /rest/v2/logging/loggers/{loggerName}
Data Grid removes the logger identified by {loggerName}, effectively reverting to the use of the root logger configuration.
If operation processed successfully, the service returns a response code 204 (No Content).
2.8. Using Server Tasks
Retrieve, execute, and upload Data Grid server tasks.
2.8.1. Retrieving Server Tasks Information
View information about available server tasks with GET requests.
GET /rest/v2/tasks
Table 2.38. Request Parameters
| Parameter | Required or Optional | Value |
|---|---|---|
|
| OPTIONAL |
|
Data Grid responds with a list of available tasks. The list includes the names of tasks, the engines that handle tasks, the named parameters for tasks, the execution modes of tasks, either ONE_NODE or ALL_NODES, and the allowed security role in JSON format, as in the following example:
[
{
"name": "SimpleTask",
"type": "TaskEngine",
"parameters": [
"p1",
"p2"
],
"execution_mode": "ONE_NODE",
"allowed_role": null
},
{
"name": "RunOnAllNodesTask",
"type": "TaskEngine",
"parameters": [
"p1"
],
"execution_mode": "ALL_NODES",
"allowed_role": null
},
{
"name": "SecurityAwareTask",
"type": "TaskEngine",
"parameters": [],
"execution_mode": "ONE_NODE",
"allowed_role": "MyRole"
}
]2.8.2. Executing Tasks
Execute tasks with POST requests that include the task name, an optional cache name and required parameters prefixed with param.
POST /rest/v2/tasks/SimpleTask?action=exec&cache=mycache¶m.p1=v1¶m.p2=v2
Data Grid responds with the task result.
2.8.3. Uploading Script Tasks
Upload script tasks with PUT or POST requests.
Supply the script as the content payload of the request. After Data Grid uploads the script, you can execute it with GET requests.
POST /rest/v2/tasks/taskName
2.8.4. Downloading Script Tasks
Download script tasks with GET requests.
GET /rest/v2/tasks/taskName?action=script
2.9. Working with Data Grid Security
View and modify security information.
2.9.1. Retrieving the ACL of a user
View information about the user’s principals and access-control list.
GET /rest/v2/security/user/acl
Data Grid responds with information about the user who has performed the request. The list includes the principals of the user, and a list of resources and the permissions that user has when accessing them.
{
"subject": [
{
"name": "deployer",
"type": "NamePrincipal"
}
],
"global": [
"READ", "WRITE", "EXEC", "LISTEN", "BULK_READ", "BULK_WRITE", "CREATE", "MONITOR", "ALL_READ", "ALL_WRITE" ],
"caches": {
"___protobuf_metadata": [
"READ", "WRITE", "EXEC", "LISTEN", "BULK_READ", "BULK_WRITE", "CREATE", "MONITOR", "ALL_READ", "ALL_WRITE"
],
"mycache": [
"LIFECYCLE", "READ", "WRITE", "EXEC", "LISTEN", "BULK_READ", "BULK_WRITE", "ADMIN", "CREATE", "MONITOR", "ALL_READ", "ALL_WRITE"
],
"___script_cache": [
"READ", "WRITE", "EXEC", "LISTEN", "BULK_READ", "BULK_WRITE", "CREATE", "MONITOR", "ALL_READ", "ALL_WRITE"
]
}
}2.9.2. Flushing the ACL cache
Flush the access-control list cache across the cluster.
POST /rest/v2/security/cache?action=flush
2.9.3. Retrieving the available roles
View all the available roles defined in the server.
GET /rest/v2/security/roles
Data Grid responds with a list of available roles. If authorization is enabled, only a user with the ADMIN permission can call this API.
["observer","application","admin","monitor","deployer"]
2.9.4. Retrieving the roles for a principal
View all the roles which map to a principal.
GET /rest/v2/security/roles/some_principal
Data Grid responds with a list of available roles for the specified principal. The principal need not exist in the realm in use.
["observer"]
2.9.5. Granting roles to a principal
Grant one or more new roles to a principal.
PUT /rest/v2/security/roles/some_principal?action=grant&role=role1&role=role2
Table 2.39. Request Parameters
| Parameter | Required or Optional | Value |
|---|---|---|
|
| REQUIRED | The name of a role |
2.9.6. Denying roles to a principal
Remove one or more roles that were previously granted to a principal.
PUT /rest/v2/security/roles/some_principal?action=deny&role=role1&role=role2
Table 2.40. Request Parameters
| Parameter | Required or Optional | Value |
|---|---|---|
|
| REQUIRED | The name of a role |