PrizmDoc Viewer v13.5 - Updated
Cluster Management
API Reference > PrizmDoc Server API > Cluster Management

Introduction

NOTE: The cluster management 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.

These are advanced URLs which allow administrators of a PrizmDoc Server cluster to dynamically inform their servers whenever other servers are brought into or out of rotation.

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:

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

URL Description
GET /PCCIS/V1/Service/Properties/Servers Returns the active list of servers a particular server knows about.
PUT /PCCIS/V1/Service/Properties/Servers Sets the active list of servers a particular server should use.

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.

Error Responses

Status Code Reason Phrase Description
403 Forbidden Can occur if you send the request to a server's cluster port instead of its public port.

Example

In this example:

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

Name Description
Content-Type Should be application/json

Request Body

JSON indicating the new active list of servers to use:

Successful Response

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

Error Responses

Status Code Reason Phrase Description
400 Bad Request The request body could not be understood. Make sure that it is syntactically valid JSON and that it contains the required data.
403 Forbidden Can occur if you send the request to a server's cluster port instead of its public port.

Example

In this example:

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": "192.168.0.1",
      "port": "18682"
    },
    {
      "address": "192.168.0.2",
      "port": "18682"
    },
    {
      "address": "192.168.0.3",
      "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.