PrizmDoc® v14.1 Release - Updated
PrizmDoc / API Reference / PrizmDoc Server REST API / Self-Hosted Administration / Cluster Management
In This Topic
    Cluster Management
    In This Topic

    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 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

    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 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

    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 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

    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 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.