This is a prerelease version.

View latest

Get started with REST API using Docker

6.0-SNAPSHOT 5.5 5.4 5.3 5.2 5.1 5.0

This tutorial provides a step-by-step guide to help you enable, run and use the REST API with minimal configuration using Docker.

Before You Begin

To complete this tutorial, you need the following:

Prerequisites Useful resources

Docker image for Hazelcast Enterprise Edition full distribution and an Enterprise Edition license

Get Started with Hazelcast Enterprise Edition

Step 1. Prepare configuration file

Create a hazelcast.yaml (or xml) configuration file with the following content and place it in the ~/config directory on your local machine.

  • XML

  • YAML

<hazelcast>
    <license-key>your license key</license-key> (1)
    <rest enabled="true">
        <security-realm>restRealm</security-realm>
    </rest>
    <security enabled="true">
        <realms>
            <realm name="restRealm">
                <authentication>
                    <simple>
                        <user username="restuser" password="restpassword">
                            <role>admin</role>
                        </user>
                    </simple>
                </authentication>
                <access-control-service>
                    <factory-class-name>com.hazelcast.internal.rest.access.DefaultAccessControlServiceFactory</factory-class-name>
                </access-control-service>
            </realm>
        </realms>
    </security>
</hazelcast>
hazelcast:
  license-key: <your license key> (1)
  rest:
    enabled: true
    security-realm: restRealm
  security:
    enabled: true
    realms:
      - name: restRealm
        authentication:
          simple:
            users:
              - username: 'restuser'
                password: 'restpassword'
                roles:
                  - admin
        access-control-service:
          factory-class-name: com.hazelcast.internal.rest.access.DefaultAccessControlServiceFactory
1 Replace <your license key> with your Hazelcast Enterprise Edition license key.

Step 2. Start Hazelcast Enterprise Edition server

To start the Hazelcast Enterprise Edition server, run the following command:

  • Using XML Config

  • Using YAML Config

docker run \
    -p 5701:5701 -p 8443:8443\
    -e JAVA_OPTS="-Dhazelcast.config=/opt/hazelcast/config_ext/hazelcast.xml" -v ~/config:/opt/hazelcast/config_ext hazelcast/hazelcast-enterprise:5.5.2
docker run \
    -p 5701:5701 -p 8443:8443\
    -e JAVA_OPTS="-Dhazelcast.config=/opt/hazelcast/config_ext/hazelcast.yaml" -v ~/config:/opt/hazelcast/config_ext hazelcast/hazelcast-enterprise:5.5.2

This command starts the member and configures it using your configuration file. In these examples, ~/config is the path to the directory containing your configuration file.

You should see a message in the console indicating that the REST service is enabled, similar to the following:

com.hazelcast.internal.rest.init.RestServiceImpl
INFO: [192.168.0.24]:5701 [dev] [5.5.0-SNAPSHOT] Hazelcast REST Service is enabled on port: 8443 with security realm: restRealm and access control service: com.hazelcast.internal.rest.access.DefaultAccessControlService

Step 3. Access the REST API and Swagger UI

The REST API is running on port 8443. You can access the Swagger UI at: http://localhost:8443/swagger-ui/index.html. This user interface displays detailed documentation for the Hazelcast REST API, and enables you to interact with the API within the cluster.

You can also view this Swagger UI within this documentation.

Step 4. Obtain a token to access all endpoints

To obtain a token, send a POST request to the endpoint at /hazelcast/rest/api/v1/token.

  • Using Swagger UI

  • Using cURL

  • Open the Swagger UI at http://localhost:8443/swagger-ui/index.html

  • Navigate to the token endpoint under the JWT Token Controller section

  • Click Try it out

  • Set the request body as follows:

    {
  "username": "restuser",
  "password": "restpassword"
}

  • Click Execute

  • Run the following command in your terminal:

    curl -X 'POST' \
  'http://localhost:8443/hazelcast/rest/api/v1/token' \
  -H 'Content-Type: application/json' \
  -d '{
  "username": "restuser",
  "password": "restpassword"
}'

Step 5. Execute a Hazelcast REST call

You need to add the token as the Authorization header in all requests, or you will get an access denied response.

  • Using Swagger UI

  • Using cURL

Click Authorize and enter the token in the provided field. After a successful authorization, any subsequent requests made using the Swagger UI will add the token into the proper request header automatically.

Example request with Swagger UI:

  • Navigate to the /hazelcast/rest/api/v1/cluster endpoint under the Cluster Controller section

  • Click Try it out

  • Click Execute

When you want to access a Hazelcast REST endpoint, you need to add the token to your requests as follows, replacing <add token here> with your actual token:

-H 'Authorization: Bearer <add token here>'

Example request with cURL:

curl -X 'GET' \
'http://localhost:8443/hazelcast/rest/api/v1/cluster' \
-H 'Authorization: Bearer <add token here>'

Next Steps

If you’re interested in learning more about the topics introduced in this tutorial, see Enterprise REST API.

lifebuoy

Help and support