Introduction

For customers self-hosting PrizmDoc Server, the cluster management REST API allows you to inform a PrizmDoc Server instance whenever a new instance is added to or removed from the cluster.

NOTE: The cluster management REST API is only available if 1) you are self-hosting PrizmDoc Server and 2) you have clustering enabled. If you are using PrizmDoc Cloud, or if you are self-hosting in single-server mode, the URLs discussed in this page will not be available.

Each PrizmDoc Server instance in a cluster has its own list of the host and port of all servers it considers to be in the cluster (including itself). Each server uses its list when deciding how to route internal traffic within the cluster. In order for your cluster to function correctly, it is important that every server in the cluster always have a correct list of active servers.

There are two cluster management URLs:

• A GET which returns the active list of servers a particular server knows about
• A PUT which changes the active list of servers a particular server should use

Unlike other PrizmDoc Server APIs, requests to these URLs should be sent directly to individual servers (rather than to, say, a load balancer which you have put in front of your cluster which would route the request to a random server). Additionally, requests to these URLs must be sent to a server's public port (not it's cluster port, otherwise you will receive 403 Forbidden).

Whenever a server is added to or removed from your cluster, you should send a PUT request to every server in the cluster informing them of the new active list of servers they should use.

For more information, see PrizmDoc Cluster Mode.

Available URLs

GET /PCCIS/V1/Service/Properties/Servers

Gets the active list servers which a particular server is currently using to route requests to. The list of servers returned here must first have been set by a request to PUT /PCCIS/V1/Service/Properties/Servers or via the Central Configuration file.

Successful Response

Response Body

JSON containing the list of host addresses and ports which this server is currently using to route requests to.

• servers (Array of Objects) List of servers which this server is currently using to route requests to. Each item in the array will be an object containing:
  • address (String) Hostname or IP address where internal traffic should be sent
  • port (String) The cluster port where internal traffic should be sent (typically "18682"). The cluster port for a server is configured via the network.clustering.clusterPort property in the Central Configuration file.

Error Responses

Example

In this example:

• The Central Configuration file uses a network.publicPort value of 18681
• The Central Configuration file uses a network.clustering.clusterPort value of 18682 (used by PrizmDoc Services for internal communication between servers)

The GET request must be sent to a specific server at its public port (18681):

GET http://192.168.0.1:18681/PCCIS/V1/Service/Properties/Servers

The returned data shows the list of all servers (including the server the request was sent to) with their internal cluster port (as a string, "18682"):

HTTP/1.1 200 OK
Content-Type: application/json

{
  "servers": [
    {
      "address": "192.168.0.1",
      "port": "18682"
    },
    {
      "address": "192.168.0.2",
      "port": "18682"
    },
    {
      "address": "192.168.0.3",
      "port": "18682"
    }
  ]
}

PUT /PCCIS/V1/Service/Properties/Servers

Sets the active list of servers which a particular server should start using to route requests to. The list of servers should include the server this request is sent to.

Request

Request Headers

Request Body

JSON indicating the new active list of servers to use:

• servers (Array of Objects) Required. List of servers which this server should start using to route requests to. Each item in the array must be an object containing:
  • address (String) Required. Hostname or IP address where internal traffic should be sent. When the network.clustering.scheme is set to "https", server addresses specified here must match the Common Name or a Subject Alternative Name specified in the corresponding server's certificate. On production servers, this usually means using fully qualified domain names of your servers.
  • port (String) Required. The cluster port where internal traffic should be sent (typically "18682"). The cluster port for a server is configured via the network.clustering.clusterPort property in the Central Configuration file.

Successful Response

A plain HTTP 200 without any body indicating the new list was accepted and will be used by the server.

Error Responses

Example

In this example:

• The Central Configuration file uses a network.publicPort value of 18681
• The Central Configuration file uses a network.clustering.clusterPort value of 18682 (used by PrizmDoc Services for internal communication between servers)
• The Central Configuration file uses a network.clustering.scheme for the specified server address.

The PUT request must be sent to a specific server at its public port (18681), but the items in the server list must use the internal cluster port (as a string, "18682").

PUT http://192.168.0.1:18681/PCCIS/V1/Service/Properties/Servers
Content-Type: application/json

{
  "servers": [
    {
      "address": "server1.mycompany.net",
      "port": "18682"
    },
    {
      "address": "server2.mycompany.net",
      "port": "18682"
    },
    {
      "address": "server3.mycompany.net",
      "port": "18682"
    }
  ]
}

HTTP/1.1 200 OK

The response of HTTP 200 indicates the new list was accepted and will be used by the server.