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¶
| 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. |
|
| 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
|
| 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
|
| 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
| 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": {} }
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
}
|