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.
NOTE: We will be defaulting to multi-server/cluster mode for PrizmDoc in a future release.
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
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.
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 sentport
(String) The cluster port where internal traffic should be sent (typically"18682"
). The cluster port for a server is configured via thenetwork.clustering.clusterPort
property in the Central Configuration file.
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 Central Configuration file uses a
network.publicPort
value of18681
- The Central Configuration file uses a
network.clustering.clusterPort
value of18682
(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
Name | Description |
---|---|
Content-Type |
Should be application/json |
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 thenetwork.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 thenetwork.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
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 Central Configuration file uses a
network.publicPort
value of18681
- The Central Configuration file uses a
network.clustering.clusterPort
value of18682
(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.