API v2: Pools

Pools serve grouping purposes for the server objects based on the same protocol to be managed within other objects (for example, accounts) as one server.


Data Structures

PoolModel
Attribute Type Required Description
id string yes Read-only object Identifier
name string yes Unique pool’s name
description string no  
created_at datetime   Read-only
modified_at datetime   Read-only
removed boolean   Read-only
servers object-array   Read-only; expensive to use; JSON object array containing id, mask, name, port and address of assigned servers.
server_ids string-array   Read-only; hidden; expensive to use
server_names string-array   Read-only; hidden; expensive to use
protocol string   Read-only; expensive to use.
builtin boolean   Read-only; expensive to use; if true, the object is not editable.
hidden boolean   Read-only; expensive to use; if true, the object is hidden in UI.

Request for Retrieving Available Attributes of the PoolModel

Method 
GET
Path 
/api/v2/objspec/pool
ServerPoolModel
Attribute Type Required Description
id string yes Read-only object Identifier.
pool_id string yes Immutable. Uniqueness is required in the combination of attribute pool_id with attribute server_id.
server_id string yes Immutable. Uniqueness is required in the combination of attribute server_id with attribute pool_id.
pool_name string   Read-only; Expensive to use.
server_name string   Read-only; Expensive to use.
server_protocol string   Read-only; Expensive to use.
created_at datetime   Read-only.
modified_at datetime   Read-only.
removed boolean   Read-only.

Request for Retrieving Available Attributes of the ServerPoolModel

Method 
GET
Path 
/api/v2/objspec/pool_server
PoolGrantAssignmentModel
Attribute Type Required Description
id string   Read-only, protected object Identifier
to_user_id string yes Immutable. Expects unique for_pool_id
for_pool_id string yes Immutable. Expects unique to_user_id
for_pool_name string   Read-only, expensive to use
to_user_name string   Read-only, expensive to use
to_user_role string   Read-only, expensive to use
created_at string   Read-only
modified_at string   Read-only
removed boolean   Read-only

Request for Retrieving Available Attributes of the PoolGrantAssignmentModel

Deprecated since version 5.5

Please note that the endpoints described in this subsection have been deprecated and are scheduled for removal in the next major release.

Method 
GET
Path 
/api/v2/objspec/pool_grant

Note

To check allowed methods, available URL parameters and possible responses please refer to the API Overview section.

The next chapter describes procedures for creating separate requests.

Refer to the Batch operations topic to create nested requests for operating on the Pool objects.


Retrieving Pools List

Request

Method 
GET
Path 
/api/v2/pool

Example Request

Sending GET https://10.0.0.0/api/v2/pool

Response

    {
"result": "success",
"pool": [
    {
        "id": "1232678819172646913",
        "name": "Linux servers",
        "description": "Example Linux pool",
        "created_at": "2022-10-20 02:01:38.373501-07",
        "modified_at": "2022-10-20 02:01:38.373501-07",
        "servers": [
            "1202678819172646913"
        ]
    },
    {
        "id": "41232678819172646914",
        "name": "Windows servers",
        "description": "Example Windows pool",
        "created_at": "2022-10-20 02:01:38.376251-07",
        "modified_at": "2022-10-20 02:01:38.376251-07",
        "servers": [
            "1202678819172646914"
        ]
    },
    {
        "id": "1232678819172646915",
        "name": "test-pool",
        "created_at": "2022-10-24 06:34:53.510281-07",
        "modified_at": "2022-10-24 06:34:53.510281-07",
        "servers": [
            "1202678819172646913"
        ]}]}

Retrieving a Pool

Request

Method 
GET
Path 
/api/v2/pool/<id>

Example Request

Sending GET https://10.0.0.0/api/v2/pool/1232678819172646915

Response

    {
"result": "success",
"pool": {
    "id": "1232678819172646915",
    "name": "test-pool",
    "created_at": "2022-10-24 06:34:53.510281-07",
    "modified_at": "2022-10-24 06:34:53.510281-07",
    "servers": [
        "1202678819172646913"
    ]}}

Creating a Pool

Request

Method 
POST
Path 
/api/v2/pool
Headers 
Content-Type: Application/JSON
Body 
PoolModel

Example Request

Sending POST https://10.0.0.0/api/v2/pool

{"name": "my-2nd-pool"}

Response

    { "result": "success",
"pool": {
    "id": "1202678819172646916" }}

Modifying a Pool

Request

Method 
PATCH
Path 
/api/v2/pool/<id>
Headers 
Content-Type: Application/JSON
Body 
PoolModel

Example Request

Sending PATCH https://10.0.0.0/api/v2/pool/1202678819172646916

{"name": "my-cool-pool"}

Response

{ "result": "success" }

Retrieving Server Pools

Request

Method 
GET
Path 
/api/v2/pool/server

Example Request

Sending GET https://10.0.0.0/api/v2/pool/server

Response

    {
"result": "success",
"pool_server": [
    {
        "pool_id": "1232678819172646913",
        "server_id": "1232678819172646913",
        "created_at": "2022-10-20 02:01:38.374809-07",
        "modified_at": "2022-10-20 02:01:38.374809-07"
    },
    {
        "pool_id": "1232678819172646914",
        "server_id": "1232678819172646914",
        "created_at": "2022-10-20 02:01:38.376536-07",
        "modified_at": "2022-10-20 02:01:38.376536-07"
    },
    {
        "pool_id": "1232678819172646915",
        "server_id": "1232678819172646913",
        "created_at": "2022-10-24 06:51:46.780733-07",
        "modified_at": "2022-10-24 06:51:46.780733-07"
    }]}

Adding a Server to the Pool

Request

Method 
POST
Path 
/api/v2/pool/server
Headers 
Content-Type: Application/JSON
Body 
ServerPoolModel

Example Request

Sending POST https://10.0.0.0/api/v2/pool/server

     { "pool_id": "4602678819172646916",
"server_id": "4602678819172646914"}

Response

    { "result": "success",
"pool_server": {} }

Deleting a Server From a Pool

Request

Method 
DELETE
Path 
/api/v2/pool/<pool_id>/server/<server_id>

Retrieving Users Allowed to Manage Pools

Deprecated since version 5.5

Please note that the endpoints described in this subsection have been deprecated and are scheduled for removal in the next major release.

Request

Method 
GET
Path 
/api/v2/grant/pool

Example Request

Sending GET https://10.0.0.0/api/v2/grant/pool

Response

    {
"result": "success",
"pool_grant": [
    {
        "for_pool_id": "1232678819172646916",
        "to_user_id": "1232678819172646915",
        "created_at": "2022-10-26 04:08:38.907148-07",
        "modified_at": "2022-10-26 04:08:38.907148-07"
    }]}

Granting Access for User to a Pool

Deprecated since version 5.5

Please note that the endpoints described in this subsection have been deprecated and are scheduled for removal in the next major release.

Request

Method 
POST
Path 
/api/v2/grant/pool
Headers 
Content-Type: Application/JSON
Body 
{
to_user_id: 1234567890,
for_pool_id: 1234567891
}

Deleting a Pool

Request

Method 
DELETE
Path 
/api/v2/pool/<id>