This is a prerelease version.

View latest

Clustered REST

The clustered REST API can be enabled to allow you to monitor clustered statistics of distributed objects through HTTP endpoints.

Enabling Clustered REST

The REST API is disabled by default.

To enable clustered REST in Management Center, use the hazelcast.mc.rest.enabled property at startup.

Root Endpoint

The entry point for the clustered REST API is /rest. This resource does not have any attributes.

Parameters

All parameters that are used in the REST endpoints, such as cluster names and distributed data structure names, must be URL encoded. Such parameters are marked in braces ({ and }) in the URL description for each endpoint. For example, name.with/special@chars parameter value would be encoded as name.with%2Fspecial%40chars.

If no data can be found for an endpoint, that endpoint returns a 404 HTTP status code.

Authentication

Unless the security provider is set to dev mode, users need an authentication (auth) token to send requests to the REST API.

The auth token must be included in the following header:

  • Authorization: Bearer <user_auth_token>

Generating Auth Tokens

The way in which you generate an auth token depends on the security provider that you use. See Security Providers.

All auth tokens inherit roles from the user.
Security Provider Method for issuing tokens

Local Security Provider

Use the user issue-token task of the hz-mc conf tool.

Send a POST request to the /api/tokens endpoint.

All other security providers other than dev mode

Send a POST request to the /api/tokens endpoint.

To use the /api/tokens endpoint, do the following. Replace the <username> and <password> placeholders with a user’s username and password.

curl -u {<username>}:{<password>} -d '{"username":"<username>"}' -H "Content-Type: application/json" -X POST http://localhost:8080/api/tokens

To use the hz-mc conf tool, do the following:

  • Linux and Mac

  • Windows

hz-mc conf user issue-token -n <username>
mc-conf.bat user issue-token -n <username>

The created token is displayed in the output:

Successfully issued a token for user 'test_user'.
Token: 'mJMMDfaSWZ1MuqhmGhA8m4erCNZtPi_A4_VyR_y8eH0'
Label: 'test_user_2021-07-07T17:24 EEST'

Revoking Auth Tokens

To revoke all auth tokens for a user, use the user revoke-tokens task.

  • Linux and Mac

  • Windows

hz-mc conf user revoke-tokens -n <username>
mc-conf.bat user revoke-tokens -n <username>

OpenAPI Definitions

The Clustered REST endpoints are documented in OpenAPI format. See the following:

This documentation is also accessible at the /swagger-ui/index.html endpoint of Management Center. For example http://localhost:8080/swagger-ui/index.html.