diff --git a/antora-playbook.yml b/antora-playbook.yml index ea9c91fc8..2596a71aa 100644 --- a/antora-playbook.yml +++ b/antora-playbook.yml @@ -12,6 +12,9 @@ content: - url: . branches: HEAD start_path: docs + - url: https://github.com/hazelcast/hazelcast-mono + branches: [master] + start_path: docs/rest ui: bundle: url: https://github.com/hazelcast/hazelcast-docs-ui/releases/latest/download/ui-bundle.zip #../hazelcast-docs-ui/build/ui-bundle.zip @@ -32,4 +35,5 @@ asciidoc: ucd: User Code Deployment extensions: - ./docs-tabs-library/tabs-block.js - - asciidoctor-kroki \ No newline at end of file + - asciidoctor-kroki + - ./lib/swagger-ui-block-macro.js \ No newline at end of file diff --git a/docs/modules/clients/partials/rest-deprecation.adoc b/docs/modules/clients/partials/rest-deprecation.adoc index 8b0a1cafe..34dcdd81f 100644 --- a/docs/modules/clients/partials/rest-deprecation.adoc +++ b/docs/modules/clients/partials/rest-deprecation.adoc @@ -1,5 +1,5 @@ [CAUTION] -.Deprecation Notice for the REST API +.Deprecation Notice for the Community Edition REST API ==== -The REST API has been deprecated and will be removed as of Hazelcast version 7.0. An improved version of this feature is under development. +The Community Edition REST API has been deprecated and will be removed as of Hazelcast version 7.0. An improved version of this feature is under development. For more info, see xref:maintain-cluster:enterprise-rest-api.adoc[REST API] ==== \ No newline at end of file diff --git a/docs/modules/maintain-cluster/images/rest-api-swagger-clicking-execute-button.png b/docs/modules/maintain-cluster/images/rest-api-swagger-clicking-execute-button.png new file mode 100644 index 000000000..254b49fb2 Binary files /dev/null and b/docs/modules/maintain-cluster/images/rest-api-swagger-clicking-execute-button.png differ diff --git a/docs/modules/maintain-cluster/images/rest-api-swagger-clicking-try-it-out-button.png b/docs/modules/maintain-cluster/images/rest-api-swagger-clicking-try-it-out-button.png new file mode 100644 index 000000000..927e58449 Binary files /dev/null and b/docs/modules/maintain-cluster/images/rest-api-swagger-clicking-try-it-out-button.png differ diff --git a/docs/modules/maintain-cluster/images/rest-api-swagger-expanding-an-endpoint.png b/docs/modules/maintain-cluster/images/rest-api-swagger-expanding-an-endpoint.png new file mode 100644 index 000000000..9af759712 Binary files /dev/null and b/docs/modules/maintain-cluster/images/rest-api-swagger-expanding-an-endpoint.png differ diff --git a/docs/modules/maintain-cluster/images/rest-api-swagger-listed-endpoints.png b/docs/modules/maintain-cluster/images/rest-api-swagger-listed-endpoints.png new file mode 100644 index 000000000..267028536 Binary files /dev/null and b/docs/modules/maintain-cluster/images/rest-api-swagger-listed-endpoints.png differ diff --git a/docs/modules/maintain-cluster/pages/enterprise-rest-api.adoc b/docs/modules/maintain-cluster/pages/enterprise-rest-api.adoc new file mode 100644 index 000000000..a09e7d6a6 --- /dev/null +++ b/docs/modules/maintain-cluster/pages/enterprise-rest-api.adoc @@ -0,0 +1,476 @@ += REST API +[[enterprise-rest-api]] +:page-enterprise: true + +Hazelcast provides a REST API that allows you to access your data +structures and cluster using the HTTP/HTTPS protocols. + +You can interact with the API using various tools and platforms such as cURL, REST clients (like Postman and Insomnia), or programming languages with HTTP request libraries or built-in support. The REST API also comes with a Swagger UI that offers an easy navigation and testing the API calls. See <>. + +In this section, we use cURL to provide the request examples. + +NOTE: REST API is only available in the {enterprise-product-name} Edition. +Hazelcast also offered a Community Edition REST API, but this has been deprecated and will be removed as of Hazelcast version 7.0. For more info, see xref:rest-api.adoc[Community Edition REST API]. + +== Enabling REST API + +REST service is **disabled** in the configuration by default; enable it as shown in the following configuration. + +NOTE: If you are using Hazelcast's xref:getting-started:editions.adoc#slim-distribution[slim distribution], you must add `hazelcast-enterprise-rest-{full-version}.jar` to your member's classpath to use the REST API. If you are working with the full distribution, this additional step is not needed. + +[tabs] +==== +XML:: ++ +-- +[source,xml] +---- + + + ... + + +---- +-- + +YAML:: ++ +[source,yaml] +---- +hazelcast: + rest: + enabled: true +---- +==== + +== Changing Default Port + +`8443` is the default port for REST API. To change it to another port, update the `rest` configuration as shown in the following example. + +[tabs] +==== +XML:: ++ +-- +[source,xml] +---- + + + 8080 + + +---- +-- + +YAML:: ++ +[source,yaml] +---- +hazelcast: + rest: + enabled: true + port: 8080 +---- +==== + +== Authentication + +You must secure the communication with REST API by configuring its authentication and access control. + +=== Configuring Authentication + +REST supports simple authentication based on username, password and user roles; see xref:security:simple-authentication.adoc[Simple Authentication]. To configure the simple authentication in the REST API, complete the following steps: + +* **#Enable REST API:#** +You need to enable the REST API. + +* **#Define A Security Realm:#** +You need to define the security realm within the rest configuration. + +* **#Enable Security:#** +You need to enable the security to use REST API. + +* **#Configure Rest Realm:#** +You need to introduce a REST realm as the authentication mechanism. This realm will handle user authentication using a simple method based on username and password. + +* **#Setup Users and Roles:#** +You should identify users and their roles within the REST realm. + +* **#Configure AccessControlService:#** +To configure `AccessControlService`, you should provide a factory class that creates an instance of the service. `AccessControlService` delegates authentication to the configured security realm. You can either create a custom factory class, or use the default implementation. For the default implementation, you can use `DefaultAccessControlServiceFactory`, to produce `DefaultAccessControlService`. Authorization decisions in this service are based on three predefined roles: `reader`, who can make requests via GET endpoints only; `writer`, who can make requests including GET, POST, and DELETE; and `admin`, who can make all requests and access admin-specific endpoints. + +The following configuration example includes all the steps listed above. + +[tabs] +==== +XML:: ++ +-- +[source,xml] +---- + + + restRealm + + + + + + + + admin + + + + <1> + com.hazelcast.internal.rest.access.DefaultAccessControlServiceFactory + + + + + +---- +-- + +YAML:: ++ +[source,yaml] +---- +hazelcast: + rest: + enabled: true + security-realm: restRealm + security: + enabled: true + realms: + - name: restRealm + authentication: + simple: + users: + - username: 'restuser' + password: 'restpassword' + roles: + - admin + access-control-service: <1> + factory-class-name: com.hazelcast.internal.rest.access.DefaultAccessControlServiceFactory +---- +==== +<1> To configure `AccessControlService`, you should provide a factory class that creates an instance of the service. `AccessControlService` delegates authentication to the configured security realm. You can either create a custom factory class, or use the default implementation. For the default implementation, you can use `DefaultAccessControlServiceFactory`, to produce `DefaultAccessControlService`. Authorization decisions in this service are based on three predefined roles: `reader`, who can make requests via GET endpoints only; `writer`, who can make requests including GET, POST, and DELETE; and `admin`, who can make all requests and access admin-specific endpoints. + +NOTE: Besides the simple authentication, you can also use other authentication types such as LDAP. See xref:security:security-realms.adoc#authentication-configuration[Authentication Configuration] on how to configure different types within a security realm. + +=== Authentication Process + +To authenticate to the REST API, the REST client must obtain a token. See the <> for details. The token request requires a username and password and the role(s) assigned to the user are included in the token as claims. You can use the token until it expires. You use the token at the `Authorization` header for each subsequent REST API call so that the call is authorized appropriately. If a valid token is not included in the header, the API will respond with a `401 Unauthorized` error. + +== HTTPS Support + +You can configure TLS/SSL in the REST API. We use Spring Boot underneath to enable Spring web services, and all the TLS/SSL related options correspond to the underlying Spring Boot TLS/SSL support capabilities. + +The TLS/SSL configuration of the REST server is completely different from Hazelcast TLS/SSL configuration which has different configuration settings. +The configuration settings are available to set up TLS/SSL as shown in +the below declarative example: + +[tabs] +==== +XML:: ++ +-- +[source,xml] +---- + + + + NEED + TLS_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_128_CBC_SHA256 + myKeyAlias + myKeyPassword + /path/to/keystore + myKeyStorePassword + JKS + SUN + /path/to/truststore + myTrustStorePassword + JKS + SUN + TLSv1.2, TLSv1.3 + TLS + /path/to/certificate + /path/to/certificate-key + /path/to/trust-certificate + /path/to/trust-certificate-key + + + +---- +-- + +YAML:: ++ +[source,yaml] +---- +hazelcast: + rest: + enabled: true + ssl: + enabled: true + client-auth: NEED + ciphers: TLS_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_128_CBC_SHA256 + enabled-protocols: TLSv1.2, TLSv1.3 + key-alias: myKeyAlias + key-password: myKeyPassword + key-store: /path/to/keystore + key-store-password: myKeyStorePassword + key-store-type: JKS + key-store-provider: SUN + trust-store: /path/to/truststore + trust-store-password: myTrustStorePassword + trust-store-type: JKS + trust-store-provider: SUN + protocol: TLS + certificate: /path/to/certificate + certificate-key: /path/to/certificate-key + trust-certificate: /path/to/trust-certificate + trust-certificate-key: /path/to/trust-certificate-key +---- +==== + +== JWT Based Authorization + +After a successful authentication by making request to the token endpoint (see <>), you will receive a short-living JWT token with assigned role names as a claim for authorization checks in subsequent REST calls. + +Token issued by one member is not trusted by other members. + +Tokens are valid for 15 minutes by default. You can update the expiry duration using the `token-validity-seconds` configuration element as shown in the following example. + +[tabs] +==== +XML:: ++ +-- +[source,xml] +---- + + + 300 + + +---- +-- + +YAML:: ++ +[source,yaml] +---- +hazelcast: + rest: + enabled: true + token-validity-seconds: 300 +---- +==== + +[#obtaining-a-token] +== Obtaining a Token + +To obtain a token, you send a `POST` request to the token endpoint at `/hazelcast/rest/api/v1/token`. The request must include JSON-formatted `username` and `password` which you <>. If the authentication is successful, you get a response which contains a valid token for the expiry duration. + +Example request using cURL: + +[source,shell] +---- +curl -X 'POST' \ + 'http://localhost:8443/hazelcast/rest/api/v1/token' \ + -H 'Content-Type: application/json' \ + -d '{ + "username": "restuser", + "password": "restpassword" +}' +---- + +It returns the following response if successful: + +[source,json] +---- +{ + "token": "" +} +---- + +It returns the following response if the provided credentials are incorrect: + +[source,json] +---- +{ + "statusCode": 401, + "message": "Username/password provided don't match the expected values." +} +---- + +== Accessing the Swagger UI + +Hazelcast REST API's Swagger UI provides information about each endpoint, including required parameters, request and response structures and types, potential response codes, and example responses. You can use this UI to easily navigate and test different API calls directly from the interface. To access it: + +. Enable the REST API. +. Start a Hazelcast member. +. Go to `http://:/swagger-ui/index.html` where and are the running member's IP address/hostname and port, respectively. + +The following is an example view: + +image::rest-api-swagger-listed-endpoints.png[] + +On the Swagger page, each endpoint is listed with a caret icon on the right side. Click the caret icon to expand the details for an endpoint. For this example, let's expand the `GET /hazelcast/rest/api/v1/cluster` endpoint. + +image::rest-api-swagger-expanding-an-endpoint.png[] + +After expanding the endpoint, let's proceed to send a request. Click the `Try it out` button, enter the parameters (if any). There are no parameters for this example. + +image::rest-api-swagger-clicking-execute-button.png[] + +Click the `Execute` button to send the request. You can see the response in the **Server response** section as shown below. You can also see the executed cURL command in the **Curl** section. + +image::rest-api-swagger-clicking-try-it-out-button.png[] + +== GET/POST/DELETE HTTP Request Examples + +All the requests in the REST API can return one of the following response types. + +* Successful void/boolean response which does not have a body. + +* Successful response which returns data in JSON format. For example: + +[source,json] +---- +{ + "nodeState": "ACTIVE", + "clusterState": "ACTIVE", + "numberOfMembers": 1 +} +---- + +* Error response in JSON format. For example: + +[source,json] +---- +{ + "statusCode": 400, + "message": "Please provide a valid value." +} +---- + +=== Retrieving Cluster Status + +You can send a `GET` request to the endpoint at `/hazelcast/rest/api/v1/cluster` to retrieve the status of your cluster. + +Example request using cURL: + +[source,shell] +---- +curl -X 'GET' \ + 'http://localhost:8443/hazelcast/rest/api/v1/cluster' \ + -H 'Authorization: Bearer ' +---- + +It returns the following response if successful: + +[source,json] +---- +{ + "members": [ + { + "address": "[192.168.0.24]:5701", + "liteMember": false, + "localMember": true, + "uuid": "3d8b9c35-a35f-461a-9e7f-d64e3f1f0f03", + "memberVersion": "5.5.0" + } + ], + "clientCount": 0, + "allConnectionCount": 0, + "state": "ACTIVE", + "version": "5.5" +} +---- + +=== Retrieving Cluster State + +You can send a `GET` request to the endpoint at `/hazelcast/rest/api/v1/cluster/state` to retrieve the state of your cluster. + +Example request using cURL: + +[source,shell] +---- +curl -X 'GET' \ + 'http://localhost:8443/hazelcast/rest/api/v1/cluster/state' \ + -H 'Authorization: Bearer ' +---- + +It returns the following response if successful: + +[source,json] +---- +{ + "state": "ACTIVE" +} +---- + +=== Changing Cluster State + +You can send a `POST` request to the endpoint at `/hazelcast/rest/api/v1/cluster/state` to change the state of your cluster. You must provide the new state within the request body in the JSON format. Valid states are `ACTIVE`, `NO_MIGRATION`, `FROZEN`, `PASSIVE`. + +Example request using cURL: + +[source,shell] +---- +curl -X 'POST' \ + 'http://localhost:8443/hazelcast/rest/api/v1/cluster/state' \ + -H 'Authorization: Bearer Bearer ' \ + -H 'Content-Type: application/json' \ + -d '{ + "state": "PASSIVE" +}' +---- + +* It returns 200 response without body if successful. +* It returns 400 response if provided state is not a valid cluster state. For example: + +[source,json] +---- +{ + "statusCode": 400, + "message": "FOOBAR is not a valid ClusterState. Please provide one of the valid values: [ACTIVE, NO_MIGRATION, FROZEN, PASSIVE]" +} +---- + +=== Destroying a CP Group + +You can send a `DELETE` request to the endpoint at `/hazelcast/rest/api/v1/cp/groups/{group-name}` to unconditionally destroy the given active CP group. + +Example request using cURL: + +[source,shell] +---- +curl -X 'DELETE' \ + 'http://localhost:8443/hazelcast/rest/api/v1/cp/groups/my-group' \ + -H 'Authorization: Bearer Bearer ' +---- + +* It returns 200 response without body if successful. +* It returns 400 response if you try to destroy METADATA group. For example: + +[source,json] +---- +{ + "statusCode": 400, + "message": "Meta data CP group [METADATA] cannot be destroyed!" +} +---- + +* It returns 500 response if CP subsystem is not enabled: + +[source,json] +---- +{ + "statusCode": 500, + "message": "CP Subsystem is not enabled!" +} +---- diff --git a/docs/modules/maintain-cluster/pages/rest-api-swagger.adoc b/docs/modules/maintain-cluster/pages/rest-api-swagger.adoc new file mode 100644 index 000000000..1a35ad223 --- /dev/null +++ b/docs/modules/maintain-cluster/pages/rest-api-swagger.adoc @@ -0,0 +1,5 @@ += Swagger UI for REST API +:page-enterprise: true +:page-layout: swagger + +swagger_ui::{attachmentsdir}/api-docs.yaml[] diff --git a/docs/modules/maintain-cluster/pages/rest-api.adoc b/docs/modules/maintain-cluster/pages/rest-api.adoc index 9b9a89cc1..b37535594 100644 --- a/docs/modules/maintain-cluster/pages/rest-api.adoc +++ b/docs/modules/maintain-cluster/pages/rest-api.adoc @@ -1,4 +1,4 @@ -= REST API += {open-source-product-name} REST API [[rest-api]] include::clients:partial$rest-deprecation.adoc[] diff --git a/docs/modules/maintain-cluster/partials/nav.adoc b/docs/modules/maintain-cluster/partials/nav.adoc index 37435ce09..fdc4602ef 100644 --- a/docs/modules/maintain-cluster/partials/nav.adoc +++ b/docs/modules/maintain-cluster/partials/nav.adoc @@ -5,5 +5,6 @@ ** xref:maintain-cluster:member-attributes.adoc[Filtering Members with Attributes] ** xref:maintain-cluster:lite-members.adoc[Lite Members] ** xref:maintain-cluster:shutdown.adoc[Shutting Down] -** xref:maintain-cluster:rest-api.adoc[REST API] +** xref:maintain-cluster:enterprise-rest-api.adoc[REST API] +*** xref:maintain-cluster:rest-api.adoc[Community Edition REST API] ** xref:management:cluster-utilities.adoc[Cluster Utilities] diff --git a/lib/swagger-ui-block-macro.js b/lib/swagger-ui-block-macro.js new file mode 100644 index 000000000..6cca736ef --- /dev/null +++ b/lib/swagger-ui-block-macro.js @@ -0,0 +1,20 @@ +const buildSwaggerUi = ({ specUrl }) => ` + + +` + +function blockSwaggerUiMacro ({ file }) { + return function () { + this.process((parent, specUrl) => { + specUrl = `${specUrl}` + const contentScripts = buildSwaggerUi({ specUrl }) + return this.createBlock(parent, 'pass', contentScripts) + }) + } +} + +function register (registry, context) { + registry.blockMacro('swagger_ui', blockSwaggerUiMacro(context)) +} + +module.exports.register = register diff --git a/package.json b/package.json index a4c97dbe0..7136b85dd 100644 --- a/package.json +++ b/package.json @@ -14,10 +14,14 @@ "devDependencies": { "@antora/cli": "^3.1.1", "@antora/site-generator": "^3.1.1", + "@asciidoctor/core": "^2.0.0", + "@djencks/antora-aggregate-collector": "^0.1.0-beta.1", "@jcahills/antora-link-checker": "^1.0.1", + "asciidoctor-kroki": "^0.10.0", "ngrok": "^3.3.0", - "serve": "^11.3.2", - "@asciidoctor/core": "^2.0.0", - "asciidoctor-kroki": "^0.10.0" + "serve": "^11.3.2" + }, + "dependencies": { + "redoc": "^2.1.4" } }