Ignite Quick Start Guide for REST API
This chapter explains system requirements for running Ignite, including how to install Ignite, start a cluster, and run a simple Hello World example using Ignite’s REST API.
Prerequisites
Ignite was tested on:
JDK |
Oracle JDK 8, 11 or 17 Open JDK 8, 11 or 17, IBM JDK 8, 11 or 17 |
OS |
Linux (any flavor), Mac OSX (10.6 and up), Windows (XP and up), Windows Server (2008 and up), Oracle Solaris |
ISA |
x86, x64, SPARC, PowerPC |
Network |
No restrictions (10G recommended) |
Installing Ignite
To get started with the Apache Ignite binary distribution:
-
Download the Ignite binary as a zip archive.
-
Unzip the zip archive into the installation folder in your system.
-
(Optional) Enable required modules.
-
(Optional) Set the
IGNITE_HOME
environment variable or Windows PATH to point to the installation folder and make sure there is no trailing/
(or\
for Windows) in the path.
Once that’s done, you will need to enable HTTP connectivity.
To do this, copy the ignite-rest-http
module from {IGNITE_HOME}/libs/optional/
to the {IGNITE_HOME}/libs
folder.
Starting a Node
Before connecting to Ignite via the REST API, you must start at least one cluster node.
You can start a node from the command line using the default configuration or by passing a custom configuration file. You can start as many nodes as you like and they will all automatically discover each other.
Navigate into the bin
folder of the Ignite installation directory from the command shell.
Your command might look like this:
cd {IGNITE_HOME}/bin/
cd {IGNITE_HOME}\bin\
Start a node with a custom configuration file that is passed as a parameter to ignite.sh|bat
like this:
./ignite.sh ../examples/config/example-ignite.xml
ignite.bat ..\examples\config\example-ignite.xml
You will see output similar to this:
[08:53:45] Ignite node started OK (id=7b30bc8e) [08:53:45] Topology snapshot [ver=1, locNode=7b30bc8e, servers=1, clients=0, state=ACTIVE, CPUs=4, offheap=1.6GB, heap=2.0GB]
Open another tab from your command shell and run the same command again:
./ignite.sh ../examples/config/example-ignite.xml
ignite.bat ..\examples\config\example-ignite.xml
Check the Topology snapshot
line in the output.
Now you have a cluster of two server nodes with more CPUs and RAM available cluster-wide:
[08:54:34] Ignite node started OK (id=3a30b7a4) [08:54:34] Topology snapshot [ver=2, locNode=3a30b7a4, servers=2, clients=0, state=ACTIVE, CPUs=4, offheap=3.2GB, heap=4.0GB]
Note
|
By default, ignite.sh|bat starts a node with the default configuration file: config/default-config.xml .
|
Running Your First Application
Once the cluster is started, you can use the Ignite REST API to perform cache operations.
You don’t need to explicitly configure anything because the connector is initialized automatically, listening on port 8080.
To verify the connector is ready, use curl:
curl "http://localhost:8080/ignite?cmd=version"
You should see a message like this:
$ curl "http://localhost:8080/ignite?cmd=version"
{"successStatus":0,"error":null,"sessionToken":null,"response":"2.16.0"}
You can see in the result that Ignite version is 2.16.0.
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'
Assuming that the server node is running locally, here is a simple example that creates a cache (myCache) and then puts and gets the string "Hello_World!" from the cache via the REST API:
Create a cache:
curl "http://localhost:8080/ignite?cmd=getorcreate&cacheName=myCache"
Put data into the cache. The default type is "string" but you can specify a data type via the keyType
parameter.
curl "http://localhost:8080/ignite?cmd=put&key=1&val="Hello_World!"&cacheName=myCache"
Get the data from the cache
curl "http://localhost:8080/ignite?cmd=get&key=1&cacheName=myCache"
Now that you’ve seen a very basic example of accessing Ignite clusters via the REST API, you should probably keep the following in mind:
-
This is a very basic example. You will want to read more on the REST API here. That page includes a listing of the various API calls and also covers important subjects like Authentication.
-
The REST interface may not be suitable for all tasks. For example, you should use one of the language clients instead if you’re trying to load bulk data, or perform mission critical tasks with millisecond latency.
Apache, Apache Ignite, the Apache feather and the Apache Ignite logo are either registered trademarks or trademarks of The Apache Software Foundation.