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
Parameter 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 string-array   Read-only

Request for retrieving available attributes of the PoolModel

Method 
GET
Path 
/api/v2/objspec/pool
ServerPoolModel
Parameter Type Required Description
id string yes Read-only object Identifier
pool_id string yes Immutable. Expects unique server_id
server_id string yes Immutable. Expects unique pool_id
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
Parameter 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
to_user_name string   Read-only, expensive to use
for_pool_name 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

Method 
GET
Path 
/api/v2/objspec/pool_grant

Allowed methods

GET for reading data of an existing object; no request body is required
POST for creating an object; requires a request body, specified in JSON format, that contains the values for properties of the object that is about to be created
PATCH for modifying an existing object; requires a request body, specified in JSON format, that contains the values for properties of the object
DELETE for removing an existing object; no request body is required

There is a list of URL parameters available for a specific method to be included within a path:

  • fields - for including the object fields in the query,

  • filter - narrows out the result with available additions:

    • in - include possible field values (separated with comma),
    • match - include a sequence of characters to be searched in field values,
    • eq - equal,
    • ne - not equal,
    • lt - less than,
    • le - less or equal,
    • gt - greater than,
    • ge - greater than or equal
    • blocked - filter blocked objects,
    • !blocked - filter unblocked objects,
    • isempty() - filter objects with empty values in specified fields, only applies to arrays (e.g., server.isnull()),

  • order,

  • offset,

  • limit,

  • debug - for showing statistics, database errors, etc,

  • total_count,

  • reveal - to see objects: active, removed, or all for both removed and un-removed.

An example of the request that shows a list of 10 users that have a role user with their id and name specified, sorted alphabetically by their names and shows a total count of users that match the given criteria: GET https://<fudo_address>/api/v2/user?fields=id,name&filter=role.eq(user)&order=name&limit=10&total_count


Possible responses

Code Status  
200 success OK
201 success CREATED
400 failure BAD REQUEST; message examples: Unrecognized endpoint, Request body is not allowed for this endpoint
401 failure UNAUTHORIZED
404 failure BAD REQUEST; message example: Object not found

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

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

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>