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.
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:
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
Serverconstructor parameter was renamed fromthreadpool(Jetty 9.4) tothreadPool(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.
HandlerCollectionandHandlerListwere 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
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:
Use the authenticate command with
ignite.login=[user]&ignite.password=[password]parameters.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 theversioncommand:
In both examples above, replace [host], [port], [user], and [password] with actual values.
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.
This page is: Copyright © 2026 MariaDB. All rights reserved.
Last updated
Was this helpful?

