For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs.
Skip to content

Using the REST API

Enable and configure the GridGain 8 REST API — the ignite-rest-http module, Jetty 12 configuration, HTTPS, and REST security.

To enable HTTP connectivity, make sure that the ignite-rest-http module is enabled. If you use the binary distribution, copy the ignite-rest-http module from IGNITE_HOME/libs/optional/ to the IGNITE_HOME/libs folder. See Enabling modules for details.

The ignite-rest-http module runs on Jetty 12. The Jetty 9.4 module and the separate ignite-rest-http-jetty-12 module of GridGain 8.9.x are removed. If you upgrade from 8.9.x and use a custom Jetty XML file, see Migrating a Jetty XML File from Jetty 9.4.

Explicit configuration is not required; the connector starts up automatically and listens on port 8080. You can check if it works with curl:

curl 'http://localhost:8080/ignite?cmd=version'

Request parameters may be provided as either a part of URL or in a form data:

curl 'http://localhost:8080/ignite?cmd=put&cacheName=myCache' -X POST -H 'Content-Type: application/x-www-form-urlencoded' -d 'key=testKey&val=testValue'

Configuration

You can change HTTP server parameters as follows:

<bean class="org.apache.ignite.configuration.IgniteConfiguration" id="ignite.cfg">
    <property name="connectorConfiguration">
        <bean class="org.apache.ignite.configuration.ConnectorConfiguration">
            <property name="jettyPath" value="jetty.xml"/>
        </bean>
    </property>
</bean>
IgniteConfiguration cfg = new IgniteConfiguration();
cfg.setConnectorConfiguration(new ConnectorConfiguration().setJettyPath("jetty.xml"));
// This example loads configuration from a file.
// You can use a custom configuration following the instructions in jetty documentation at https://jetty.org/.
private static class JettyServerFactory implements Factory<Server> {

    private static final long serialVersionUID = 0L;

    @Override public Server create() {
        log.info(">>>>> Using custom Jetty server initialization.");

        URL cfgUrl = U.resolveIgniteUrl(JETTY_CFG_PATH);

        // Jetty 12: load the file through a closeable ResourceFactory and call configure() inside the block.
        try (ResourceFactory.Closeable resFactory = ResourceFactory.closeable()) {
            XmlConfiguration cfg = new XmlConfiguration(resFactory.newResource(cfgUrl));

            return (Server)cfg.configure();
        }
        catch (FileNotFoundException e) {
            throw new IgniteSpiException("Failed to find configuration file: " + cfgUrl, e);
        }
        catch (SAXException e) {
            throw new IgniteSpiException("Failed to parse configuration file: " + cfgUrl, e);
        }
        catch (IOException e) {
            throw new IgniteSpiException("Failed to load configuration file: " + cfgUrl, e);
        }
        catch (IgniteException e) {
            throw e;
        }
        catch (Exception e) {
            throw new IgniteException("Failed to start Jetty HTTP server.", e);
        }
    }
}

public IgniteConfiguration createIgniteConfiguration() {
    IgniteConfiguration igniteConfig = new IgniteConfiguration();

    ConnectorConfiguration connectorConfig = new ConnectorConfiguration();
    connectorConfig.setJettyServerFactory(new JettyServerFactory());

    igniteConfig.setConnectorConfiguration(connectorConfig);

    return igniteConfig;
}

unsupported

The following table describes the properties of ConnectorConfiguration that are related to the http server:

Parameter Name
Description
Optional
Default Value

setSecretKey(String)

Defines secret key used for client authentication. When provided, client request must contain HTTP header X-Signature with the string "[1]:[2]", where [1] is timestamp in milliseconds and [2] is the Base64 encoded SHA1 hash of the secret key.

Yes

null

setPortRange(int)

Port range for Jetty server. If the port provided in Jetty configuration or IGNITE_JETTY_PORT system property is already in use, Ignite iteratively increments port by 1 and tries to bind once again until provided port range is exceeded.

Yes

100

setJettyPath(String)

Path to Jetty configuration file. Should be either absolute or relative to IGNITE_HOME. If the path is not set, GridGain starts a Jetty server with a simple HTTP connector. This connector uses IGNITE_JETTY_HOST and IGNITE_JETTY_PORT system properties as host and port respectively. If IGNITE_JETTY_HOST is not provided, localhost is used as default. If IGNITE_JETTY_PORT is not provided, port 8080 is used.

Yes

null

setMessageInterceptor(ConnectorMessageInterceptor)

The interceptor provides the ability to transform all objects exchanged via REST protocol. For example, if you use custom serialization on client you can write an interceptor to transform binary representations received from the client to Java objects and later access them from Java code directly.

Yes

null

Example Jetty XML Configuration

Path to this configuration should be set to ConnectorConfiguration.setJettyPath(String) as explained above.

Migrating a Jetty XML File from Jetty 9.4

A Jetty XML file written for the Jetty 9.4 module of GridGain 8.9.x does not load on Jetty 12. The node fails to start with Failed to start Jetty HTTP server and IllegalStateException: No matching constructor class org.eclipse.jetty.server.Server. A configuration that does not set setJettyPath(String) needs no changes. If you pass a custom configuration file with setJettyPath(String), apply the following changes:

  • Rename the server thread-pool argument. The Server constructor parameter was renamed from threadpool (Jetty 9.4) to threadPool (Jetty 12). A named <Arg name="threadpool"> no longer matches the constructor and makes the whole constructor unmatchable. Rename it, or drop the name to use a positional argument:

  • Remove the handler block. HandlerCollection and HandlerList were removed in Jetty 12. GridGain installs its own REST handler after your file is applied, so any <Set name="handler">...HandlerCollection...</Set> block was already overridden and can be deleted.

The <!DOCTYPE ...> declaration needs no change: Jetty 12 maps the old Jetty 9 public and system identifiers to its current DTD.

Configuring HTTPS

The SSL connector uses org.eclipse.jetty.util.ssl.SslContextFactory$Server. A minimal HTTPS connector looks as follows:

SecureRequestCustomizer enables SNI host checking by default. If the certificate's CN or SAN does not match the address the connector binds to, disable the check with <Set name="sniHostCheck">false</Set>.

Security

Refer to the SSL/TLS Step by Step for a comprehensive instruction on SSL.

When authentication is configured in the cluster, all applications that use REST API request authentication by providing security credentials. The authentication request returns a session token that can be used with any command within that session.

There are two ways to request authorization:

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

  2. Use any REST command with ignite.login=[user]&ignite.password=[password] parameters in the path of your connection string. In our example below, we use the version command:

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

REST authentication works on per-node basis. When working with multiple nodes in the same cluster, get the credentials for each node you need individually.

Executing any one of the above strings in a browser returns a response with a session token which looks like this:

Once you obtain the session token, use the sessionToken parameter with your connection string as shown in the example below:

In the above connection string, replace [host], [port], and [sessionToken] with actual values.

Session Token Expiration

A session token is valid only for 30 seconds. Using an expired session token results in an error, like the one below:

To set a custom expire time, set the system variable: IGNITE_REST_SESSION_TIMEOUT (in seconds).

This page is: Copyright © 2026 MariaDB. All rights reserved.

Last updated

Was this helpful?