Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Data Grid REST API

Red Hat Data Grid 8.3

Configure and interact with the Data Grid REST API

Red Hat Customer Content Services

Abstract

Access data, monitor and maintain clusters, perform administrative operations through the Data Grid REST API.

Red Hat Data Grid
Copy link

Data Grid is a high-performance, distributed in-memory data store.

Schemaless data structure
Flexibility to store different objects as key-value pairs.
Grid-based data storage
Designed to distribute and replicate data across clusters.
Elastic scaling
Dynamically adjust the number of nodes to meet demand without service disruption.
Data interoperability
Store, retrieve, and query data in the grid from different endpoints.

Data Grid documentation
Copy link

Documentation for Data Grid is available on the Red Hat customer portal.

Data Grid downloads
Copy link

Access the Data Grid Software Downloads on the Red Hat customer portal.

Note

You must have a Red Hat account to access and download Data Grid software.

Making open source more inclusive
Copy link

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.

Chapter 1. Data Grid REST Endpoint
Copy link

Data Grid servers provide RESTful HTTP access to data through a REST endpoint built on Netty.

1.1. REST Authentication
Copy link

Configure authentication to the REST endpoint with the Data Grid command line interface (CLI) and the user command. The CLI lets you create and manage users, passwords, and authorization roles for accessing the REST endpoint.

Reference

1.2. Supported Protocols
Copy link

The Data Grid REST endpoint supports HTTP/1.1 and HTTP/2 protocols.

You can do either of the following to use HTTP/2:

Note

TLS/ALPN with JDK8 requires additional client configuration. Refer to the appropriate documentation for your REST client. In most cases you need to use either the Jetty ALPN Agent or OpenSSL bindings.

1.3. Data Formats and the REST API
Copy link

Data Grid caches store data in formats that you can define with a MediaType.

See the Cache Encoding and Marshalling for more information about MediaTypes and encoding data with Data Grid.

The following example configures the storage format for entries: 

<distributed-cache>
   <encoding>
      <key media-type="application/x-java-object"/>
      <value media-type="application/xml; charset=UTF-8"/>
   </encoding>
</distributed-cache>
Copy to Clipboard Toggle word wrap

If you do not configure a MediaType, Data Grid defaults to application/octet-stream for both keys and values. However, if the cache is indexed, Data Grid defaults to application/x-protostream.

1.3.1. Supported Formats
Copy link

You can write and read data in different formats and Data Grid can convert between those formats when required.

The following "standard" formats are interchangeable:

  • application/x-java-object
  • application/octet-stream
  • application/x-www-form-urlencoded
  • text/plain

You can also convert the preceding data formats into the following formats:

  • application/xml
  • application/json
  • application/x-jboss-marshalling
  • application/x-protostream
  • application/x-java-serialized

Data Grid also lets you convert between application/x-protostream and application/json.

All calls to the REST API can provide headers describing the content written or the required format of the content when reading. Data Grid supports the standard HTTP/1.1 headers "Content-Type" and "Accept" that are applied for values, plus the "Key-Content-Type" with similar effect for keys.

1.3.2. Accept Headers
Copy link

The Data Grid REST endpoint is compliant with the RFC-2616 Accept header and negotiates the correct MediaType based on the conversions supported.

For example, send the following header when reading data: 

Accept: text/plain;q=0.7, application/json;q=0.8, */*;q=0.6
Copy to Clipboard Toggle word wrap

The preceding header causes Data Grid to first return content in JSON format (higher priority 0.8). If it is not possible to convert the storage format to JSON, Data Grid attempts the next format of text/plain (second highest priority 0.7). Finally, Data Grid falls back to */*, which picks a suitable format based on the cache configuration.

1.3.3. Names with Special Characters
Copy link

The creation of any REST resource requires a name that is part of the URL, and in case this name contains any special characters as defined in Section 2.2 of the RFC 3986 spec, it is necessary to encode it with the Percent encoding mechanism.

1.3.4. Key-Content-Type Headers
Copy link

Most REST API calls have the Key included in the URL. Data Grid assumes the Key is a java.lang.String when handling those calls, but you can use a specific header Key-Content-Type for keys in different formats.

Key-Content-Type Header Examples

  • Specifying a byte[] Key as a Base64 string:

API call: 

`PUT /my-cache/AQIDBDM=`
Copy to Clipboard Toggle word wrap

Headers:

Key-Content-Type: application/octet-stream

  • Specifying a byte[] Key as a hexadecimal string:

API call:

GET /my-cache/0x01CA03042F

Headers: 

Key-Content-Type: application/octet-stream; encoding=hex
Copy to Clipboard Toggle word wrap
  • Specifying a double Key:

API call:

POST /my-cache/3.141456

Headers: 

Key-Content-Type: application/x-java-object;type=java.lang.Double
Copy to Clipboard Toggle word wrap

The type parameter for application/x-java-object is restricted to:

  • Primitive wrapper types
  • java.lang.String
  • Bytes, making application/x-java-object;type=Bytes equivalent to application/octet-stream;encoding=hex.

1.3.5. JSON/Protostream Conversion
Copy link

When caches are indexed, or specifically configured to store application/x-protostream, you can send and receive JSON documents that are automatically converted to and from Protobuf.

You must register a Protobuf schema for the conversion to work.

To register protobuf schemas via REST, invoke a POST or PUT in the ___protobuf_metadata cache as in the following example: 

curl -u user:password -X POST --data-binary @./schema.proto http://127.0.0.1:11222/rest/v2/caches/___protobuf_metadata/schema.proto
Copy to Clipboard Toggle word wrap

When writing JSON documents, a special field _type must be present in the document to identity the Protobuf Message that corresponds to the document.

Person.proto

message Person  {
  required string name = 1;
  required int32 age = 2;
}
Copy to Clipboard Toggle word wrap

Person.json

{
   "_type": "Person",
   "name": "user1",
   "age": 32
}
Copy to Clipboard Toggle word wrap

1.4. Cross-Origin Resource Sharing (CORS) Requests
Copy link

The Data Grid REST connector supports CORS, including preflight and rules based on the request origin.

The following shows an example REST connector configuration with CORS rules: 

<rest-connector name="rest1" socket-binding="rest" cache-container="default">
   <cors-rules>
      <cors-rule name="restrict host1"
                 allow-credentials="false">
         <allowed-origins>http://host1,https://host1</allowed-origins>
         <allowed-methods>GET</allowed-methods>
      </cors-rule>
      <cors-rule name="allow ALL"
                 allow-credentials="true"
                 max-age-seconds="2000">
         <allowed-origins>*</allowed-origins>
         <allowed-methods>GET,OPTIONS,POST,PUT,DELETE</allowed-methods>
         <allowed-headers>Key-Content-Type</allowed-headers>
      </cors-rule>
   </cors-rules>
</rest-connector>
Copy to Clipboard Toggle word wrap

Data Grid evaluates CORS rules sequentially based on the "Origin" header set by the browser.

In the preceding example, if the origin is either "http://host1" or "https://host1", then the rule "restrict host1" applies. If the origin is different, then the next rule is tested.

Because the "allow ALL" rule permits all origins, any script that has an origin other than "http://host1" or "https://host1" can perform the allowed methods and use the supplied headers.

For information about configuring CORS rules, see the Data Grid Server Configuration Schema.

The VM property infinispan.server.rest.cors-allow can be used when starting the server to allow all permissions to one or more origins. Example: 

./bin/server.sh -Dinfinispan.server.rest.cors-allow=http://192.168.1.78:11222,http://host.mydomain.com
Copy to Clipboard Toggle word wrap

All origins specified using this method will take precedence over the configured rules.

The Data Grid REST API lets you monitor, maintain, and manage Data Grid deployments and provides access to your data.

Note

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

Create and manage Data Grid caches and perform operations on data.

2.1.1. Creating Caches
Copy link

Create named caches across Data Grid clusters with POST requests that include XML or JSON configuration in the payload. 

POST /rest/v2/caches/{cacheName}
Copy to Clipboard Toggle word wrap
Expand
Table 2.1. Headers
HeaderRequired or OptionalParameter

Content-Type

REQUIRED

Sets the MediaType for the Data Grid configuration payload; either application/xml or application/json.

Flags

OPTIONAL

Used to set AdminFlags

2.1.1.1. Cache configuration
Copy link

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.

Important

Data Grid restricts characters to a maximum of 255 for a cache name or a cache template name. If you exceed this character limit, the Data Grid server might abruptly stop without issuing an exception message. Write succinct cache names and cache template names.

Important

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 cache names and cache template 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"/>
  </indexing>
  <partition-handling when-split="ALLOW_READ_WRITES"
                      merge-policy="PREFERRED_NON_NULL"/>
  <persistence passivation="false">
    <!-- Persistent storage configuration. -->
  </persistence>
</distributed-cache>
Copy to Clipboard Toggle word wrap

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"
      }
    },
    "partition-handling" : {
      "when-split" : "ALLOW_READ_WRITES",
      "merge-policy" : "PREFERRED_NON_NULL"
    },
    "persistence" : {
      "passivation" : false
    }
  }
}
Copy to Clipboard Toggle word wrap

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"
  partitionHandling:
    whenSplit: "ALLOW_READ_WRITES"
    mergePolicy: "PREFERRED_NON_NULL"
  persistence:
    passivation: "false"
    # Persistent storage configuration.
Copy to Clipboard Toggle word wrap

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"/>
  </indexing>
  <partition-handling when-split="ALLOW_READ_WRITES"
                      merge-policy="PREFERRED_NON_NULL"/>
  <persistence passivation="false">
    <!-- Persistent storage configuration. -->
  </persistence>
</replicated-cache>
Copy to Clipboard Toggle word wrap

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"
      }
    },
    "partition-handling" : {
      "when-split" : "ALLOW_READ_WRITES",
      "merge-policy" : "PREFERRED_NON_NULL"
    },
    "persistence" : {
      "passivation" : false
    }
  }
}
Copy to Clipboard Toggle word wrap

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"
  partitionHandling:
    whenSplit: "ALLOW_READ_WRITES"
    mergePolicy: "PREFERRED_NON_NULL"
  persistence:
    passivation: "false"
    # Persistent storage configuration.
Copy to Clipboard Toggle word wrap

Multiple caches

XML

<infinispan
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="urn:infinispan:config:13.0 https://infinispan.org/schemas/infinispan-config-13.0.xsd
                          urn:infinispan:server:13.0 https://infinispan.org/schemas/infinispan-server-13.0.xsd"
      xmlns="urn:infinispan:config:13.0"
      xmlns:server="urn:infinispan:server:13.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>
Copy to Clipboard Toggle word wrap

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"
Copy to Clipboard Toggle word wrap

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"
            }
          }
        }
      }
    }
  }
}
Copy to Clipboard Toggle word wrap

2.1.2. Modifying Caches
Copy link

Make changes to attributes in cache configurations across Data Grid clusters with PUT requests that include XML or JSON configuration in the payload.

Note

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}
Copy to Clipboard Toggle word wrap
Expand
Table 2.2. Headers
HeaderRequired or OptionalParameter

Content-Type

REQUIRED

Sets the MediaType for the Data Grid configuration payload; either application/xml or application/json.

Flags

OPTIONAL

Used to set AdminFlags

2.1.3. Verifying Caches
Copy link

Check if caches are available in Data Grid clusters with HEAD requests. 

HEAD /rest/v2/caches/{cacheName}
Copy to Clipboard Toggle word wrap

2.1.4. Creating Caches with Templates
Copy link

Create caches from Data Grid templates with POST requests and the ?template= parameter. 

POST /rest/v2/caches/{cacheName}?template={templateName}
Copy to Clipboard Toggle word wrap
Tip

2.1.5. Retrieving Cache Configuration
Copy link

Retrieve Data Grid cache configurations with GET requests. 

GET /rest/v2/caches/{name}?action=config
Copy to Clipboard Toggle word wrap
Expand
Table 2.3. Headers
HeaderRequired or OptionalParameter

Accept

OPTIONAL

Sets the required format to return content. Supported formats are application/xml and application/json. The default is application/json. See Accept for more information.

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
Copy to Clipboard Toggle word wrap

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>'
Copy to Clipboard Toggle word wrap

2.1.7. Retrieving All Cache Details
Copy link

Invoke a GET request to retrieve all details for Data Grid caches. 

GET /rest/v2/caches/{name}
Copy to Clipboard Toggle word wrap

Data 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
}
Copy to Clipboard Toggle word wrap
  • stats current stats of the cache.
  • size the estimated size for the cache.
  • configuration the cache configuration.
  • rehash_in_progress true when a rehashing is in progress.
  • indexing_in_progress true when indexing is in progress.
  • rebalancing_enabled is 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.
  • bounded when expiration is enabled.
  • indexed true if the cache is indexed.
  • persistent true if the cache is persisted.
  • transactional true if the cache is transactional.
  • secured true if the cache is secured.
  • has_remote_backup true if the cache has remote backups.
  • key_storage the media type of the cache keys.
  • value_storage the media type of the cache values.
Note

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.

Invoke a GET request to retrieve all mutable cache configuration attributes for Data Grid caches. 

GET /rest/v2/caches/{name}?action=get-mutable-attributes
Copy to Clipboard Toggle word wrap

Data 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"
]
Copy to Clipboard Toggle word wrap

Add the full parameter to obtain values and type information: 

GET /rest/v2/caches/mycache?action=get-mutable-attributes&full=true
Copy to Clipboard Toggle word wrap

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"
  }
}
Copy to Clipboard Toggle word wrap

For attributes of type enum, an additional universe property will contain the set of possible values.

2.1.9. Updating cache configuration attributes
Copy link

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}
Copy to Clipboard Toggle word wrap

2.1.10. Adding Entries
Copy link

Add entries to caches with POST requests. 

POST /rest/v2/caches/{cacheName}/{cacheKey}
Copy to Clipboard Toggle word wrap

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.

Expand
Table 2.4. Headers
HeaderRequired or OptionalParameter

Key-Content-Type

OPTIONAL

Sets the content type for the key in the request. See Key-Content-Type for more information.

Content-Type

OPTIONAL

Sets the MediaType of the value for the key.

timeToLiveSeconds

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.

maxIdleTimeSeconds

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.

flags

OPTIONAL

The flags used to add the entry. See Flag for more information.

Note

The flags header also applies to all other operations involving data manipulation on the cache,

Note

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 maxIdle value from the configuration.
  • the value for timeToLiveSeconds that you pass as a request parameter or a value of -1 if you do not pass a value.

If only timeToLiveSeconds has a value of 0, Data Grid uses:

  • the default lifespan value from the configuration.
  • the value for maxIdle that you pass as a request parameter or a value of -1 if you do not pass a value.

2.1.11. Replacing Entries
Copy link

Replace entries in caches with PUT requests. 

PUT /rest/v2/caches/{cacheName}/{cacheKey}
Copy to Clipboard Toggle word wrap

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.12. Retrieving Data By Keys
Copy link

Retrieve data for specific keys with GET requests. 

GET /rest/v2/caches/{cacheName}/{cacheKey}
Copy to Clipboard Toggle word wrap

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.

Note

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.

Expand
Table 2.5. Headers
HeaderRequired or OptionalParameter

Key-Content-Type

OPTIONAL

Sets the content type for the key in the request. The default is application/x-java-object; type=java.lang.String. See Key-Content-Type for more information.

Accept

OPTIONAL

Sets the required format to return content. See Accept for more information.

Tip

Append the extended parameter to the query string to get additional information: 

GET /rest/v2/caches/{cacheName}/{cacheKey}?extended
Copy to Clipboard Toggle word wrap

The preceding request returns custom headers:

  • Cluster-Primary-Owner returns the node name that is the primary owner of the key.
  • Cluster-Node-Name returns the JGroups node name of the server that handled the request.
  • Cluster-Physical-Address returns the physical JGroups address of the server that handled the request.

2.1.13. Checking if Entries Exist
Copy link

Verify that specific entries exists with HEAD requests. 

HEAD /rest/v2/caches/{cacheName}/{cacheKey}
Copy to Clipboard Toggle word wrap

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.

Note

HEAD requests also support the extended parameter.

Expand
Table 2.6. Headers
HeaderRequired or OptionalParameter

Key-Content-Type

OPTIONAL

Sets the content type for the key in the request. The default is application/x-java-object; type=java.lang.String. See Key-Content-Type for more information.

2.1.14. Deleting Entries
Copy link

Remove entries from caches with DELETE requests. 

DELETE /rest/v2/caches/{cacheName}/{cacheKey}
Copy to Clipboard Toggle word wrap
Expand
Table 2.7. Headers
HeaderRequired or OptionalParameter

Key-Content-Type

OPTIONAL

Sets the content type for the key in the request. The default is application/x-java-object; type=java.lang.String. See Key-Content-Type for more information.

2.1.15. Deleting Caches
Copy link

Remove caches from Data Grid clusters with DELETE requests. 

DELETE /rest/v2/caches/{cacheName}
Copy to Clipboard Toggle word wrap

2.1.16. Retrieving All Keys from Caches
Copy link

Invoke GET requests to retrieve all the keys in a cache in JSON format. 

GET /rest/v2/caches/{cacheName}?action=keys
Copy to Clipboard Toggle word wrap
Expand
Table 2.8. Request Parameters
ParameterRequired or OptionalValue

limit

OPTIONAL

Specifies the maximum number of keys to retrieve using an InputStream. A negative value retrieves all keys. The default value is -1.

batch

OPTIONAL

Specifies the internal batch size when retrieving the keys. The default value is 1000.

2.1.17. Retrieving All Entries from Caches
Copy link

Invoke GET requests to retrieve all the entries in a cache in JSON format. 

GET /rest/v2/caches/{cacheName}?action=entries
Copy to Clipboard Toggle word wrap
Expand
Table 2.9. Request Parameters
ParameterRequired or OptionalValue

metadata

OPTIONAL

Includes metadata for each entry in the response. The default value is false.

limit

OPTIONAL

Specifies the maximum number of keys to include in the response. A negative value retrieves all keys. The default value is -1.

batch

OPTIONAL

Specifies the internal batch size when retrieving the keys. The default value is 1000.

content-negotiation

OPTIONAL

If true, will convert keys and values to a readable format. For caches with text encodings (e.g., text/plain, xml, json), the server returns keys and values as plain text. For caches with binary encodings, the server will return the entries as JSON if the conversion is supported, otherwise in a text hexadecimal format, e.g., 0xA123CF98. When content-negotiation is used, the response will contain two headers: key-content-type and value-content-type to described the negotiated format.

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
    }
]
Copy to Clipboard Toggle word wrap
  • key The key for the entry.
  • value The value of the entry.
  • timeToLiveSeconds Based on the entry lifespan but in seconds, or -1 if the entry never expires. It’s not returned unless you set metadata="true".
  • maxIdleTimeSeconds Maximum idle time, in seconds, or -1 if entry never expires. It’s not returned unless you set metadata="true".
  • created Time the entry was created or or -1 for immortal entries. It’s not returned unless you set metadata="true".
  • lastUsed Last time an operation was performed on the entry or -1 for immortal entries. It’s not returned unless you set metadata="true".
  • expireTime Time when the entry expires or -1 for immortal entries. It’s not returned unless you set metadata="true".

2.1.18. Clearing Caches
Copy link

To delete all data from a cache, invoke a POST request with the ?action=clear parameter. 

POST /rest/v2/caches/{cacheName}?action=clear
Copy to Clipboard Toggle word wrap

If the operation successfully completes, the service returns 204 (No Content).

2.1.19. Getting Cache Size
Copy link

Retrieve the size of caches across the entire cluster with GET requests and the ?action=size parameter. 

GET /rest/v2/caches/{cacheName}?action=size
Copy to Clipboard Toggle word wrap

2.1.20. Getting Cache Statistics
Copy link

Obtain runtime statistics for caches with GET requests. 

GET /rest/v2/caches/{cacheName}?action=stats
Copy to Clipboard Toggle word wrap

2.1.21. Listing Caches
Copy link

List all available caches in Data Grid clusters with GET requests. 

GET /rest/v2/caches/
Copy to Clipboard Toggle word wrap

2.1.22. Listening to cache events
Copy link

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=listen
Copy to Clipboard Toggle word wrap
Expand
Table 2.10. Headers
HeaderRequired or OptionalParameter

Accept

OPTIONAL

Sets the required format to return content. Supported formats are text/plain and application/json. The default is application/json. See Accept for more information.

2.1.23. Enabling rebalancing
Copy link

Turn on automatic rebalancing for a specific cache. 

POST /rest/v2/caches/{cacheName}?action=enable-rebalancing
Copy to Clipboard Toggle word wrap

2.1.24. Disabling rebalancing
Copy link

Turn off automatic rebalancing for a specific cache. 

POST /rest/v2/caches/{cacheName}?action=disable-rebalancing
Copy to Clipboard Toggle word wrap

2.1.25. Getting Cache Availability
Copy link

Retrieve the availability of a cache. 

GET /rest/v2/caches/{cacheName}?action=get-availability
Copy to Clipboard Toggle word wrap
Note

You can get the availability of internal caches but this is subject to change in future Data Grid versions.

2.1.26. Setting Cache Availability
Copy link

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}
Copy to Clipboard Toggle word wrap
Expand
Table 2.11. Request Parameters
ParameterRequired or OptionalValue

availability

REQUIRED

AVAILABLE or DEGRADED_MODE

  • AVAILABLE makes caches available to all nodes in a network partition.
  • DEGRADED_MODE prevents read and write operations on caches when network partitions occur.
Note

You can set the availability of internal caches but this is subject to change in future Data Grid versions.

2.1.27. Indexing and Querying with the REST API
Copy link

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}
Copy to Clipboard Toggle word wrap

Data Grid response

{
  "total_results" : 150,
  "hits" : [ {
    "hit" : {
      "name" : "user1",
      "age" : 35
    }
  }, {
    "hit" : {
       "name" : "user2",
       "age" : 42
    }
  }, {
    "hit" : {
       "name" : "user3",
       "age" : 12
    }
  } ]
}
Copy to Clipboard Toggle word wrap

  • total_results displays the total number of results from the query.
  • hits is an array of matches from the query.

  • hit is an object that matches the query.

    Tip

    Hits can contain all fields or a subset of fields if you use a Select clause.

Expand
Table 2.12. Request Parameters
ParameterRequired or OptionalValue

query

REQUIRED

Specifies the query string.

max_results

OPTIONAL

Sets the number of results to return. The default is 10.

offset

OPTIONAL

Specifies the index of the first result to return. The default is 0.

local

OPTIONAL

When true, the query is restricted to the data present in node that process the request. The default is false.

To use the body of the request instead of specifying query parameters, invoke POST requests as follows: 

POST /rest/v2/caches/{cacheName}?action=search
Copy to Clipboard Toggle word wrap

Query in request body

{
 "query":"from Entity where name:\"user1\"",
 "max_results":20,
 "offset":10
}
Copy to Clipboard Toggle word wrap

2.1.27.1. Re-indexing Data
Copy link

Re-index all data in caches with POST requests and the ?action=mass-index parameter. 

POST  /v2/caches/{cacheName}/search/indexes?action=mass-index
Copy to Clipboard Toggle word wrap
Expand
Table 2.13. Request Parameters
ParameterRequired or OptionalValue

mode

OPTIONAL

Values for the mode parameter are as follows:

* sync returns 204 (No Content) only after the re-indexing operation is complete.

* async returns 204 (No Content) immediately and the re-indexing operation continues running in the cluster. You can check the status with the Index Statistics REST call.

local

OPTIONAL

When true, only the data from node that process the request is re-indexed. The default is false, meaning all data cluster-wide is re-indexed.

2.1.27.2. Purging Indexes
Copy link

Delete all indexes from caches with POST requests and the ?action=clear parameter. 

POST  /rest/v2/caches/{cacheName}/search/indexes?action=clear
Copy to Clipboard Toggle word wrap

If the operation successfully completes, the service returns 204 (No Content).

2.1.27.3. Retrieving Query and Index Statistics
Copy link

Obtain information about queries and indexes in caches with GET requests.

Note

You must enable statistics in the cache configuration or results are empty. 

GET /rest/v2/caches/{cacheName}/search/stats
Copy to Clipboard Toggle word wrap
Expand
Table 2.14. Request Parameters
ParameterRequired or OptionalValue

scope

OPTIONAL

Use cluster to retrieve consolidated statistics for all members of the cluster. When omitted, Data Grid returns statistics for the local queries and indexes.

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
  }
}
Copy to Clipboard Toggle word wrap

In the query section:

  • indexed_local Provides details about indexed queries.
  • indexed_distributed Provides details about distributed indexed queries.
  • hybrid Provides details about queries that used the index only partially.
  • non_indexed Provides details about queries that didn’t use the index.
  • entity_load Provides details about cache operations to fetch objects after indexed queries execution.
Note

Time is always measured in nanoseconds.

In the index section:

  • types Provide details about each indexed type (class name or protobuf message) that is configured in the cache.

    • count The number of entities indexed for the type.
    • size Usage in bytes of the type.
  • reindexing If the value is true, the Indexer is running in the cache.
2.1.27.4. Clearing Query Statistics
Copy link

Reset runtime statistics with POST requests and the ?action=clear parameter. 

POST /rest/v2/caches/{cacheName}/search/stats?action=clear
Copy to Clipboard Toggle word wrap

Data Grid resets only query execution times for the local node only. This operation does not clear index statistics.

2.1.27.5. Retrieving Index Statistics (Deprecated)
Copy link

Obtain information about indexes in caches with GET requests. 

GET /rest/v2/caches/{cacheName}/search/indexes/stats
Copy to Clipboard Toggle word wrap

Data Grid response

{
    "indexed_class_names": ["org.infinispan.sample.User"],
    "indexed_entities_count": {
        "org.infinispan.sample.User": 4
    },
    "index_sizes": {
        "cacheName_protobuf": 14551
    },
    "reindexing": false
}
Copy to Clipboard Toggle word wrap

  • indexed_class_names Provides the class names of the indexes present in the cache. For Protobuf the value is always org.infinispan.query.remote.impl.indexing.ProtobufValueWrapper.
  • indexed_entities_count Provides the number of entities indexed per class.
  • index_sizes Provides the size, in bytes, for each index in the cache.
  • reindexing Indicates if a re-indexing operation was performed for the cache. If the value is true, the MassIndexer was started in the cache.
2.1.27.6. Retrieving Query Statistics (Deprecated)
Copy link

Get information about the queries that have been run in caches with GET requests. 

GET /rest/v2/caches/{cacheName}/search/query/stats
Copy to Clipboard Toggle word wrap

Data 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"
}
Copy to Clipboard Toggle word wrap

  • search_query_execution_count Provides the number of queries that have been run.
  • search_query_total_time Provides the total time spent on queries.
  • search_query_execution_max_time Provides the maximum time taken for a query.
  • search_query_execution_avg_time Provides the average query time.
  • object_loading_total_time Provides the total time spent loading objects from the cache after query execution.
  • object_loading_execution_max_time Provides the maximum time spent loading objects execution.
  • object_loading_execution_avg_time Provides the average time spent loading objects execution.
  • objects_loaded_count Provides the count of objects loaded.
  • search_query_execution_max_time_query_string Provides the slowest query executed.
2.1.27.7. Clearing Query Statistics (Deprecated)
Copy link

Reset runtime statistics with POST requests and the ?action=clear parameter. 

POST /rest/v2/caches/{cacheName}/search/query/stats?action=clear
Copy to Clipboard Toggle word wrap

2.1.28. Cross-Site Operations with Caches
Copy link

Perform cross-site replication operations with the Data Grid REST API.

2.1.28.1. Getting status of all backup locations
Copy link

Retrieve the status of all backup locations with GET requests. 

GET /rest/v2/caches/{cacheName}/x-site/backups/
Copy to Clipboard Toggle word wrap

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"
    ]
  }
}
Copy to Clipboard Toggle word wrap
Expand
Table 2.15. Returned Status
ValueDescription

online

All nodes in the local cluster have a cross-site view with the backup location.

offline

No nodes in the local cluster have a cross-site view with the backup location.

mixed

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.

Retrieve the status of a backup location with GET requests. 

GET /rest/v2/caches/{cacheName}/x-site/backups/{siteName}
Copy to Clipboard Toggle word wrap

Data Grid responds with the status of each node in the site in JSON format, as in the following example: 

{
  "NodeA":"offline",
  "NodeB":"online"
}
Copy to Clipboard Toggle word wrap
Expand
Table 2.16. Returned Status
ValueDescription

online

The node is online.

offline

The node is offline.

failed

Not possible to retrieve status. The remote cache could be shutting down or a network error occurred during the request.

2.1.28.3. Taking backup locations offline
Copy link

Take backup locations offline with POST requests and the ?action=take-offline parameter. 

POST /rest/v2/caches/{cacheName}/x-site/backups/{siteName}?action=take-offline
Copy to Clipboard Toggle word wrap
2.1.28.4. Bringing backup locations online
Copy link

Bring backup locations online with the ?action=bring-online parameter. 

POST /rest/v2/caches/{cacheName}/x-site/backups/{siteName}?action=bring-online
Copy to Clipboard Toggle word wrap
2.1.28.5. Pushing state to backup locations
Copy link

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-state
Copy to Clipboard Toggle word wrap
2.1.28.6. Canceling state transfer
Copy link

Cancel state transfer operations with the ?action=cancel-push-state parameter. 

POST /rest/v2/caches/{cacheName}/x-site/backups/{siteName}?action=cancel-push-state
Copy to Clipboard Toggle word wrap
2.1.28.7. Getting state transfer status
Copy link

Retrieve status of state transfer operations with the ?action=push-state-status parameter. 

GET /rest/v2/caches/{cacheName}/x-site/backups?action=push-state-status
Copy to Clipboard Toggle word wrap

Data Grid responds with the status of state transfer for each backup location in JSON format, as in the following example: 

{
   "NYC":"CANCELED",
   "LON":"OK"
}
Copy to Clipboard Toggle word wrap
Expand
Table 2.17. Returned status
ValueDescription

SENDING

State transfer to the backup location is in progress.

OK

State transfer completed successfully.

ERROR

An error occurred with state transfer. Check log files.

CANCELLING

State transfer cancellation is in progress.

2.1.28.8. Clearing state transfer status
Copy link

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-status
Copy to Clipboard Toggle word wrap
2.1.28.9. Modifying take offline conditions
Copy link

Sites go offline if certain conditions are met. Modify the take offline parameters to control when backup locations automatically go offline.

Procedure

  1. Check configured take offline parameters with GET requests and the take-offline-config parameter. 

    GET /rest/v2/caches/{cacheName}/x-site/backups/{siteName}/take-offline-config
    Copy to Clipboard Toggle word wrap

    The Data Grid response includes after_failures and min_wait fields as follows: 

    {
  "after_failures": 2,
  "min_wait": 1000
}
    Copy to Clipboard Toggle word wrap

  2. Modify take offline parameters in the body of PUT requests. 

    PUT /rest/v2/caches/{cacheName}/x-site/backups/{siteName}/take-offline-config
    Copy to Clipboard Toggle word wrap

    If the operation successfully completes, the service returns 204 (No Content).

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-state
Copy to Clipboard Toggle word wrap

2.1.29. Rolling Upgrades
Copy link

Perform rolling upgrades of cache data between Data Grid clusters

2.1.29.1. Connecting Source Clusters
Copy link

Connect a target cluster to the source cluster with: 

POST /rest/v2/caches/{cacheName}/rolling-upgrade/source-connection
Copy to Clipboard Toggle word wrap

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"
        }
      }
    }
  }
}
Copy to Clipboard Toggle word wrap

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

To obtain the remote-store definition of a cache, use a GET request: 

GET /rest/v2/caches/{cacheName}/rolling-upgrade/source-connection
Copy to Clipboard Toggle word wrap

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.

Note

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.29.3. Checking if a Cache is connected
Copy link

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
Copy to Clipboard Toggle word wrap

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.29.4. Synchronizing Data
Copy link

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-data
Copy to Clipboard Toggle word wrap

When the operation completes, Data Grid responds with the total number of entries copied to the target cluster.

2.1.29.5. Disconnecting Source Clusters
Copy link

After you synchronize data to target clusters, disconnect from the source cluster with DELETE requests: 

DELETE /rest/v2/caches/{cacheName}/rolling-upgrade/source-connection
Copy to Clipboard Toggle word wrap

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

Create, delete, and modify counters via the REST API.

2.2.1. Creating Counters
Copy link

Create counters with POST requests that include configuration in the payload. 

POST /rest/v2/counters/{counterName}
Copy to Clipboard Toggle word wrap

Example Weak Counter

{
    "weak-counter":{
        "initial-value":5,
        "storage":"PERSISTENT",
        "concurrency-level":1
    }
}
Copy to Clipboard Toggle word wrap

Example Strong Counter

{
    "strong-counter":{
        "initial-value":3,
        "storage":"PERSISTENT",
        "upper-bound":5
    }
}
Copy to Clipboard Toggle word wrap

2.2.2. Deleting Counters
Copy link

Remove specific counters with DELETE requests. 

DELETE /rest/v2/counters/{counterName}
Copy to Clipboard Toggle word wrap

2.2.3. Retrieving Counter Configuration
Copy link

Retrieve configuration for specific counters with GET requests. 

GET /rest/v2/counters/{counterName}/config
Copy to Clipboard Toggle word wrap

Data Grid responds with the counter configuration in JSON format.

2.2.4. Getting Counter Values
Copy link

Retrieve counter values with GET requests. 

GET /rest/v2/counters/{counterName}
Copy to Clipboard Toggle word wrap
Expand
Table 2.18. Headers
HeaderRequired or OptionalParameter

Accept

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

Restore the initial value of counters without POST requests and the ?action=reset parameter. 

POST /rest/v2/counters/{counterName}?action=reset
Copy to Clipboard Toggle word wrap

If the operation successfully completes, the service returns 204 (No Content).

2.2.6. Incrementing Counters
Copy link

Increment counter values with POST request` and the ?action=increment parameter. 

POST /rest/v2/counters/{counterName}?action=increment
Copy to Clipboard Toggle word wrap
Note

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

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}
Copy to Clipboard Toggle word wrap
Note

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

Decrement counter values with POST requests and the ?action=decrement parameter. 

POST /rest/v2/counters/{counterName}?action=decrement
Copy to Clipboard Toggle word wrap
Note

WEAK counters never respond after operations and return 204 (No Content).

STRONG counters return 200 (OK) and the current value after each operation.

Atomically set values for strong counters with GET requests and the compareAndSet parameter. 

POST /rest/v2/counters/{counterName}?action=compareAndSet&expect={expect}&update={update}
Copy to Clipboard Toggle word wrap

Data Grid atomically sets the value to {update} if the current value is {expect}. If the operation is successful, Data Grid returns true.

Atomically set values for strong counters with GET requests and the compareAndSwap parameter. 

POST /rest/v2/counters/{counterName}?action=compareAndSwap&expect={expect}&update={update}
Copy to Clipboard Toggle word wrap

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

Retrieve a list of counters in Data Grid clusters with GET requests. 

GET /rest/v2/counters/
Copy to Clipboard Toggle word wrap

2.3. Working with Protobuf Schemas
Copy link

Create and manage Protobuf schemas, .proto files, via the Data Grid REST API.

2.3.1. Creating Protobuf Schemas
Copy link

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}
Copy to Clipboard Toggle word wrap

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"
  }
}
Copy to Clipboard Toggle word wrap
  • name is the name of the Protobuf schema.
  • error is null for 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
Copy link

Retrieve Protobuf schema from Data Grid with GET requests. 

GET /rest/v2/schemas/{schemaName}
Copy to Clipboard Toggle word wrap

2.3.3. Updating Protobuf Schemas
Copy link

Modify Protobuf schemas with PUT requests that include the content of a protobuf file in the payload. 

PUT /rest/v2/schemas/{schemaName}
Copy to Clipboard Toggle word wrap

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"
  }
}
Copy to Clipboard Toggle word wrap
  • name is the name of the Protobuf schema.
  • error is null for valid Protobuf schemas. If Data Grid cannot successfully validate the schema, it returns errors.

2.3.4. Deleting Protobuf Schemas
Copy link

Remove Protobuf schemas from Data Grid clusters with DELETE requests. 

DELETE /rest/v2/schemas/{schemaName}
Copy to Clipboard Toggle word wrap

If the operation successfully completes, the service returns 204 (No Content).

2.3.5. Listing Protobuf Schemas
Copy link

List all available Protobuf schemas with GET requests. 

GET /rest/v2/schemas/
Copy to Clipboard Toggle word wrap

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
}]
Copy to Clipboard Toggle word wrap
  • name is the name of the Protobuf schema.
  • error is null for valid Protobuf schemas. If Data Grid cannot successfully validate the schema, it returns errors.

2.4. Working with Cache Managers
Copy link

Interact with Data Grid Cache Managers to get cluster and usage statistics.

2.4.1. Getting Basic Cache Manager Information
Copy link

Retrieving information about Cache Managers with GET requests. 

GET /rest/v2/cache-managers/{cacheManagerName}
Copy to Clipboard Toggle word wrap

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
}
Copy to Clipboard Toggle word wrap
  • version contains the Data Grid version
  • name contains the name of the cache manager as defined in the configuration
  • coordinator is true if the cache manager is the coordinator of the cluster
  • cache_configuration_names contains an array of all caches configurations defined in the cache manager
  • cluster_name contains the name of the cluster as defined in the configuration
  • physical_addresses contains the physical network addresses associated with the cache manager
  • coordinator_address contains the physical network addresses of the coordinator of the cluster
  • cache_manager_status the lifecycle status of the cache manager. For possible values, check the org.infinispan.lifecycle.ComponentStatus documentation
  • created_cache_count number of created caches, excludes all internal and private caches
  • running_cache_count number of created caches that are running
  • node_address contains the logical address of the cache manager
  • cluster_members and cluster_members_physical_addresses an array of logical and physical addresses of the members of the cluster
  • cluster_size number of members in the cluster
  • defined_caches A list of all caches defined in the cache manager, excluding private caches but including internal caches that are accessible
  • local_site The name of the local site.
    If cross-site replication is not configured, Data Grid returns "local".
  • relay_node is true if the node handles RELAY messages between clusters.
  • relay_nodes_address is an array of logical addresses for relay nodes.
  • sites_view The list of sites that participate in cross-site replication.
    If cross-site replication is not configured, Data Grid returns an empty list.
  • rebalancing_enabled is 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
Copy link

Retrieve health information for Data Grid clusters with GET requests. 

GET /rest/v2/cache-managers/{cacheManagerName}/health
Copy to Clipboard Toggle word wrap

Data 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"
        }
    ]
}
Copy to Clipboard Toggle word wrap

  • cluster_health contains the health of the cluster

    • cluster_name specifies the name of the cluster as defined in the configuration.

    • health_status provides one of the following:

      • DEGRADED indicates at least one of the caches is in degraded mode.
      • HEALTHY_REBALANCING indicates at least one cache is in the rebalancing state.
      • HEALTHY indicates all cache instances in the cluster are operating as expected.
      • FAILED indicates the cache failed to start with the provided configuration.
    • number_of_nodes displays the total number of cluster members. Returns a value of 0 for non-clustered (standalone) servers.
    • node_names is an array of all cluster members. Empty for standalone servers.

  • cache_health contains health information per-cache

    • status HEALTHY, DEGRADED, HEALTHY_REBALANCING or FAILED
    • cache_name the name of the cache as defined in the configuration.

2.4.3. Getting Cache Manager Health Status
Copy link

Retrieve the health status of Cache Managers with GET requests that do not require authentication. 

GET /rest/v2/cache-managers/{cacheManagerName}/health/status
Copy to Clipboard Toggle word wrap

Data Grid responds with one of the following in text/plain format:

  • HEALTHY
  • HEALTHY_REBALANCING
  • DEGRADED
  • FAILED

2.4.4. Checking REST Endpoint Availability
Copy link

Verify Data Grid server REST endpoint availability with HEAD requests. 

HEAD /rest/v2/cache-managers/{cacheManagerName}/health
Copy to Clipboard Toggle word wrap

If you receive a successful response code then the Data Grid REST server is running and serving requests.

Retrieve global configuration for Cache Managers with GET requests. 

GET /rest/v2/cache-managers/{cacheManagerName}/config
Copy to Clipboard Toggle word wrap
Expand
Table 2.19. Headers
HeaderRequired or OptionalParameter

Accept

OPTIONAL

The required format to return the content. Supported formats are application/json and application/xml. JSON is assumed if no header is provided.

Reference

GlobalConfiguration

2.4.6. Obtaining Configuration for All Caches
Copy link

Retrieve the configuration for all caches with GET requests. 

GET /rest/v2/cache-managers/{cacheManagerName}/cache-configs
Copy to Clipboard Toggle word wrap

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"
              }
          }
      }
  }
]
Copy to Clipboard Toggle word wrap

2.4.7. Listing Available Cache Templates
Copy link

Retrieve all available Data Grid cache templates with GET requests. 

GET /rest/v2/cache-managers/{cacheManagerName}/cache-configs/templates
Copy to Clipboard Toggle word wrap
Tip

2.4.8. Obtaining Cache Status and Information
Copy link

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}/caches
Copy to Clipboard Toggle word wrap

Data 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
}]
Copy to Clipboard Toggle word wrap

2.4.9. Getting Cache Manager Statistics
Copy link

Retrieve the statistics for Cache Managers with GET requests. 

GET /rest/v2/cache-managers/{cacheManagerName}/stats
Copy to Clipboard Toggle word wrap

Data 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
}
Copy to Clipboard Toggle word wrap
  • statistics_enabled is true if statistics collection is enabled for the Cache Manager.
  • read_write_ratio displays the read/write ratio across all caches.
  • time_since_start shows the time, in seconds, since the Cache Manager started.
  • time_since_reset shows the number of seconds since the Cache Manager statistics were last reset.
  • number_of_entries shows 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_entries shows the number of store operations performed across all caches for the Cache Manager.
  • off_heap_memory_used shows the amount, in bytes[], of off-heap memory used by this cache container.
  • data_memory_used shows the amount, in bytes[], that the current eviction algorithm estimates is in use for data across all caches. Returns 0 if eviction is not enabled.
  • misses shows the number of get() misses across all caches.
  • remove_hits shows the number of removal hits across all caches.
  • remove_misses shows the number of removal misses across all caches.
  • evictions shows the number of evictions across all caches.
  • average_read_time shows the average number of milliseconds taken for get() operations across all caches.
  • average_read_time_nanos same as average_read_time but in nanoseconds.
  • average_remove_time shows the average number of milliseconds for remove() operations across all caches.
  • average_remove_time_nanos same as average_remove_time but in nanoseconds.
  • required_minimum_number_of_nodes shows the required minimum number of nodes to guarantee data consistency.
  • hits provides the number of get() hits across all caches.
  • stores provides the number of put() operations across all caches.
  • current_number_of_entries_in_memory shows the total number of entries currently in all caches, excluding passivated entries.
  • hit_ratio provides the total percentage hit/(hit+miss) ratio for all caches.
  • retrievals shows the total number of get() operations.

2.4.10. Shutdown all container caches
Copy link

Shut down the Data Grid container on the server with POST requests. 

POST /rest/v2/container?action=shutdown
Copy to Clipboard Toggle word wrap

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.

Note

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

Turn on automatic rebalancing for all caches. 

POST /rest/v2/cache-managers/{cacheManagerName}?action=enable-rebalancing
Copy to Clipboard Toggle word wrap

2.4.12. Disabling rebalancing for all caches
Copy link

Turn off automatic rebalancing for all caches. 

POST /rest/v2/cache-managers/{cacheManagerName}?action=disable-rebalancing
Copy to Clipboard Toggle word wrap

2.4.13. Backing Up Data Grid Cache Managers
Copy link

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}
Copy to Clipboard Toggle word wrap

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:

Expand
Table 2.20. JSON Parameters
KeyRequired or OptionalValue

directory

OPTIONAL

Specifies a location on the server to create and store the backup archive.

resources

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.

Expand
Table 2.21. Resource Parameters
KeyRequired or OptionalValue

caches

OPTIONAL

Specifies either an array of cache names to back up or * for all caches.

cache-configs

OPTIONAL

Specifies either an array of cache templates to back up or * for all templates.

counters

OPTIONAL

Defines either an array of counter names to back up or * for all counters.

proto-schemas

OPTIONAL

Defines either an array of Protobuf schema names to back up or * for all schemas.

tasks

OPTIONAL

Specifies either an array of server tasks to back up or * for all tasks.

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": ["*"]
  }
}
Copy to Clipboard Toggle word wrap

2.4.14. Listing Backups
Copy link

Retrieve the names of all backup operations that are in progress, completed, or failed. 

GET /rest/v2/cache-managers/{cacheManagerName}/backups
Copy to Clipboard Toggle word wrap

Data Grid responds with an Array of all backup names as in the following example: 

["backup1", "backup2"]
Copy to Clipboard Toggle word wrap

2.4.15. Checking Backup Availability
Copy link

Verify that a backup operation is complete. 

HEAD /rest/v2/cache-managers/{cacheManagerName}/backups/{backupName}
Copy to Clipboard Toggle word wrap

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

Download backup archives from the server. 

GET /rest/v2/cache-managers/{cacheManagerName}/backups/{backupName}
Copy to Clipboard Toggle word wrap

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

Remove backup archives from the server. 

DELETE /rest/v2/cache-managers/{cacheManagerName}/backups/{backupName}
Copy to Clipboard Toggle word wrap

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.

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.

Important

You can restore resources only if the container name in the backup archive matches {cacheManagerName}. 

POST /rest/v2/cache-managers/{cacheManagerName}/restores/{restoreName}
Copy to Clipboard Toggle word wrap

A 202 response indicates that the restore request has been accepted for processing.

Use the application/json content type with your POST request to back up from an archive that is available on the server.

Expand
Table 2.22. JSON Parameters
KeyRequired or OptionalValue

location

REQUIRED

Specifies the path of the backup archive to restore.

resources

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.

Expand
Table 2.23. Resource Parameters
KeyRequired or OptionalValue

caches

OPTIONAL

Specifies either an array of cache names to back up or * for all caches.

cache-configs

OPTIONAL

Specifies either an array of cache templates to back up or * for all templates.

counters

OPTIONAL

Defines either an array of counter names to back up or * for all counters.

proto-schemas

OPTIONAL

Defines either an array of Protobuf schema names to back up or * for all schemas.

tasks

OPTIONAL

Specifies either an array of server tasks to back up or * for all tasks.

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": ["*"]
  }
}
Copy to Clipboard Toggle word wrap
2.4.18.2. Restoring from Local Backup Archives
Copy link

Use the multipart/form-data content type with your POST request to upload a local backup archive to the server.

Expand
Table 2.24. Form Data
ParameterContent-TypeRequired or OptionalValue

backup

application/zip

REQUIRED

Specifies the bytes of the backup archive to restore.

resources

application/json, text/plain

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--
Copy to Clipboard Toggle word wrap

2.4.19. Listing Restores
Copy link

Retrieve the names of all restore requests that are in progress, completed, or failed. 

GET /rest/v2/cache-managers/{cacheManagerName}/restores
Copy to Clipboard Toggle word wrap

Data Grid responds with an Array of all restore names as in the following example: 

["restore1", "restore2"]
Copy to Clipboard Toggle word wrap

2.4.20. Checking Restore Progress
Copy link

Verify that a restore operation is complete. 

HEAD /rest/v2/cache-managers/{cacheManagerName}/restores/{restoreName}
Copy to Clipboard Toggle word wrap

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

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}
Copy to Clipboard Toggle word wrap

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.

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
Copy to Clipboard Toggle word wrap
Expand
Table 2.25. Headers
HeaderRequired or OptionalParameter

Accept

OPTIONAL

Sets the required format to return content. Supported formats are application/yaml, application/json and application/xml. The default is application/yaml. See Accept for more information.

2.4.23. Cross-Site Operations with Cache Managers
Copy link

Perform cross-site operations with Cache Managers to apply the operations to all caches.

2.4.23.1. Getting status of backup locations
Copy link

Retrieve the status of all backup locations from Cache Managers with GET requests. 

GET /rest/v2/cache-managers/{cacheManagerName}/x-site/backups/
Copy to Clipboard Toggle word wrap

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"
      ]
   }
}
Copy to Clipboard Toggle word wrap
Expand
Table 2.26. Returned status
ValueDescription

online

All nodes in the local cluster have a cross-site view with the backup location.

offline

No nodes in the local cluster have a cross-site view with the backup location.

mixed

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}
Copy to Clipboard Toggle word wrap

Returns the status for a single backup location.

2.4.23.2. Taking backup locations offline
Copy link

Take backup locations offline with the ?action=take-offline parameter. 

POST /rest/v2/cache-managers/{cacheManagerName}/x-site/backups/{siteName}?action=take-offline
Copy to Clipboard Toggle word wrap
2.4.23.3. Bringing backup locations online
Copy link

Bring backup locations online with the ?action=bring-online parameter. 

POST /rest/v2/cache-managers/{cacheManagerName}/x-site/backups/{siteName}?action=bring-online
Copy to Clipboard Toggle word wrap
2.4.23.4. Retrieving the state transfer mode
Copy link

Check the state transfer mode with GET requests. 

GET /rest/v2/caches/{cacheName}/x-site/backups/{site}/state-transfer-mode
Copy to Clipboard Toggle word wrap
2.4.23.5. Setting the state transfer mode
Copy link

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}
Copy to Clipboard Toggle word wrap
2.4.23.6. Starting state transfer
Copy link

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-state
Copy to Clipboard Toggle word wrap
2.4.23.7. Canceling state transfer
Copy link

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-state
Copy to Clipboard Toggle word wrap

2.5. Working with Data Grid Servers
Copy link

Monitor and manage Data Grid server instances.

2.5.1. Retrieving Basic Server Information
Copy link

View basic information about Data Grid servers with GET requests. 

GET /rest/v2/server
Copy to Clipboard Toggle word wrap

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"
}
Copy to Clipboard Toggle word wrap

2.5.2. Getting Cache Managers
Copy link

Retrieve lists of cache managers for Data Grid servers with GET requests. 

GET /rest/v2/server/cache-managers
Copy to Clipboard Toggle word wrap

Data Grid responds with an array of the cache manager names configured for the server.

Note

Data Grid currently supports one cache manager per server only.

2.5.3. Adding Caches to Ignore Lists
Copy link

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}
Copy to Clipboard Toggle word wrap

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.

Note

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

Remove caches from the ignore list with DELETE requests. 

DELETE /rest/v2/server/ignored-caches/{cache-manager}/{cache}
Copy to Clipboard Toggle word wrap

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

Confirm that caches are ignored with GET requests. 

GET /rest/v2/server/ignored-caches/{cache-manager}
Copy to Clipboard Toggle word wrap

2.5.6. Obtaining Server Configuration
Copy link

Retrieve Data Grid server configurations with GET requests. 

GET /rest/v2/server/config
Copy to Clipboard Toggle word wrap

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"
            }
        }
    }
}
Copy to Clipboard Toggle word wrap

2.5.7. Getting Environment Variables
Copy link

Retrieve all environment variables for Data Grid servers with GET requests. 

GET /rest/v2/server/env
Copy to Clipboard Toggle word wrap

2.5.8. Getting JVM Memory Details
Copy link

Retrieve JVM memory usage information for Data Grid servers with GET requests. 

GET /rest/v2/server/memory
Copy to Clipboard Toggle word wrap

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 Thread Dumps
Copy link

Retrieve the current thread dump for the JVM with GET requests. 

GET /rest/v2/server/threads
Copy to Clipboard Toggle word wrap

Data Grid responds with the current thread dump in text/plain format.

Retrieve aggregated reports for Data Grid servers with GET requests. 

GET /rest/v2/server/report
Copy to Clipboard Toggle word wrap

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.11. Stopping Data Grid Servers
Copy link

Stop Data Grid servers with POST requests. 

POST /rest/v2/server?action=stop
Copy to Clipboard Toggle word wrap

Data Grid responds with 204 (No Content) and then stops running.

2.6. Working with Data Grid Clusters
Copy link

Monitor and perform administrative tasks on Data Grid clusters.

2.6.1. Stopping Data Grid Clusters
Copy link

Shut down entire Data Grid clusters with POST requests. 

POST /rest/v2/cluster?action=stop
Copy to Clipboard Toggle word wrap

Data Grid responds with 204 (No Content) and then performs an orderly shutdown of the entire cluster.

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}
Copy to Clipboard Toggle word wrap

Data Grid responds with 204 (No Content).

2.6.3. Backing Up Data Grid Clusters
Copy link

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}
Copy to Clipboard Toggle word wrap

Optionally include a JSON payload with your request that contains parameters for the backup operation, as follows:

Expand
Table 2.27. JSON Parameters
KeyRequired or OptionalValue

directory

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

Retrieve the names of all backup operations that are in progress, completed, or failed. 

GET /rest/v2/cluster/backups
Copy to Clipboard Toggle word wrap

Data Grid responds with an Array of all backup names as in the following example: 

["backup1", "backup2"]
Copy to Clipboard Toggle word wrap

2.6.5. Checking Backup Availability
Copy link

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}
Copy to Clipboard Toggle word wrap

2.6.6. Downloading Backup Archives
Copy link

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}
Copy to Clipboard Toggle word wrap

2.6.7. Deleting Backup Archives
Copy link

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}
Copy to Clipboard Toggle word wrap

2.6.8. Restoring Data Grid Cluster Resources
Copy link

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.

Important

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}
Copy to Clipboard Toggle word wrap

A 202 response indicates that the restore request is accepted for processing.

Use the application/json content type with your POST request to back up from an archive that is available on the server.

Expand
Table 2.28. JSON Parameters
KeyRequired or OptionalValue

location

REQUIRED

Specifies the path of the backup archive to restore.

resources

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.

Expand
Table 2.29. Resource Parameters
KeyRequired or OptionalValue

caches

OPTIONAL

Specifies either an array of cache names to back up or * for all caches.

cache-configs

OPTIONAL

Specifies either an array of cache templates to back up or * for all templates.

counters

OPTIONAL

Defines either an array of counter names to back up or * for all counters.

proto-schemas

OPTIONAL

Defines either an array of Protobuf schema names to back up or * for all schemas.

tasks

OPTIONAL

Specifies either an array of server tasks to back up or * for all tasks.

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": ["*"]
  }
}
Copy to Clipboard Toggle word wrap
2.6.8.2. Restoring from Local Backup Archives
Copy link

Use the multipart/form-data content type with your POST request to upload a local backup archive to the server.

Expand
Table 2.30. Form Data
ParameterContent-TypeRequired or OptionalValue

backup

application/zip

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--
Copy to Clipboard Toggle word wrap

2.6.9. Listing Restores
Copy link

Retrieve the names of all restore requests that are in progress, completed, or failed. 

GET /rest/v2/cluster/restores
Copy to Clipboard Toggle word wrap

Data Grid responds with an Array of all restore names as in the following example: 

["restore1", "restore2"]
Copy to Clipboard Toggle word wrap

2.6.10. Checking Restore Progress
Copy link

Verify that a restore operation is complete. 

HEAD /rest/v2/cluster/restores/{restoreName}
Copy to Clipboard Toggle word wrap

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

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}
Copy to Clipboard Toggle word wrap

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.7. Data Grid Server logging configuration
Copy link

View and modify the logging configuration on Data Grid clusters at runtime.

2.7.1. Listing the logging appenders
Copy link

View a list of all configured appenders with GET requests. 

GET /rest/v2/logging/appenders
Copy to Clipboard Toggle word wrap

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"
  }
}
Copy to Clipboard Toggle word wrap

2.7.2. Listing the loggers
Copy link

View a list of all configured loggers with GET requests. 

GET /rest/v2/logging/loggers
Copy to Clipboard Toggle word wrap

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" ]
} ]
Copy to Clipboard Toggle word wrap

2.7.3. Creating/modifying a logger
Copy link

Create a new logger or modify an existing one with PUT requests. 

PUT /rest/v2/logging/loggers/{loggerName}?level={level}&appender={appender}&appender={appender}...
Copy to Clipboard Toggle word wrap

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

Remove an existing logger with DELETE requests. 

DELETE /rest/v2/logging/loggers/{loggerName}
Copy to Clipboard Toggle word wrap

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

Retrieve, execute, and upload Data Grid server tasks.

2.8.1. Retrieving Server Tasks Information
Copy link

View information about available server tasks with GET requests. 

GET /rest/v2/tasks
Copy to Clipboard Toggle word wrap
Expand
Table 2.31. Request Parameters
ParameterRequired or OptionalValue

type

OPTIONAL

user: will exclude internal (admin) tasks from the results

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"
  }
]
Copy to Clipboard Toggle word wrap

2.8.2. Executing Tasks
Copy link

Execute tasks with POST requests that include the task name and required parameters prefixed with param. 

POST /rest/v2/tasks/SimpleTask?action=exec&param.p1=v1&param.p2=v2
Copy to Clipboard Toggle word wrap

Data Grid responds with the task result.

2.8.3. Uploading Script Tasks
Copy link

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
Copy to Clipboard Toggle word wrap

2.9. Working with Data Grid Security
Copy link

View and modify security information.

2.9.1. Retrieving the ACL of a user
Copy link

View information about the user’s principals and access-control list. 

GET /rest/v2/security/user/acl
Copy to Clipboard Toggle word wrap

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"
    ]
  }
}
Copy to Clipboard Toggle word wrap

2.9.2. Flushing the ACL cache
Copy link

Flush the access-control list cache across the cluster. 

POST /rest/v2/security/cache?action=flush
Copy to Clipboard Toggle word wrap

2.9.3. Retrieving the available roles
Copy link

View all the available roles defined in the server. 

GET /rest/v2/security/roles
Copy to Clipboard Toggle word wrap

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"]
Copy to Clipboard Toggle word wrap

2.9.4. Retrieving the roles for a principal
Copy link

View all the roles which map to a principal. 

GET /rest/v2/security/roles/some_principal
Copy to Clipboard Toggle word wrap

Data Grid responds with a list of available roles for the specified principal. The principal need not exist in the realm in use. 

["observer"]
Copy to Clipboard Toggle word wrap

2.9.5. Granting roles to a principal
Copy link

Grant one or more new roles to a principal. 

PUT /rest/v2/security/roles/some_principal?action=grant&role=role1&role=role2
Copy to Clipboard Toggle word wrap
Expand
Table 2.32. Request Parameters
ParameterRequired or OptionalValue

role

REQUIRED

The name of a role

2.9.6. Denying roles to a principal
Copy link

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
Copy to Clipboard Toggle word wrap
Expand
Table 2.33. Request Parameters
ParameterRequired or OptionalValue

role

REQUIRED

The name of a role

Legal Notice
Copy link

Copyright © 2023 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat