Rest API¶
Polemarch provides REST API for all its functionality accessible via web GUI, because our GUI also uses this API to work. Below comes information about every entity we have in Polemarch and methods applicable to it.
All methods urls stated with /api/v1/
for first api version.
With other versions number will be changed. Current documentation wrote for
version 1. All methods here placed with this prefix to simplify copy & pasting.
Pagination¶
For all kinds of objects in Polemarch pagination is used. So for every list of objects of any kind result will look like:
-
GET
/api/v1/{something}/
¶ List of something.
Results:
{ "count":40, "next":"http://localhost:8080/api/v1/hosts/?limit=5&offset=10", "previous":"http://localhost:8080/api/v1/hosts/?limit=5", "results":[ // list of objects goes here ] }
Response JSON Object: - count (number) – how many objects exists at all.
- next (string) – link to next page with objects (
null
if we at last). - previous (string) – link to previous page with objects (
null
if we at first). - results (array) – array of objects at current page.
Hosts¶
-
GET
/api/v1/hosts/{id}/
¶ Get details about one host.
Parameters: - id – id of host.
Example request:
GET /api/v1/hosts/12/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ "id":12, "name":"038108237241668497-0875926814493907", "type":"HOST", "vars":{ }, "url":"http://localhost:8080/api/v1/hosts/12/?format=json" }
Response JSON Object: - id (number) – id of host.
- name (string) – either human-readable name or hostname/IP or range of them (it is depends at context of using this host during playbooks run).
- type (string) – it is
RANGE
if name is range of IPs or hosts, otherwise isHOST
. - url (string) – url to this specific host.
- vars (object) – dictionary of variables associated with this object. See Variables for details.
-
GET
/api/v1/hosts/
¶ List of hosts. Pagination is used for this list.
Query Parameters: - id – id of host if we want to filter by it.
- name – name of host if we want to filter by it.
- id__not – id of host, which we want to filter out.
- name__not – name of host, which we want to filter out.
Example request:
GET /api/v1/hosts/?name__not=192.168.0.1 HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ "count":4, "next":null, "previous":null, "results":[ { "id":1, "name":"127.0.0.1", "type":"HOST", "url":"http://testserver/api/v1/hosts/1/" }, { "id":2, "name":"hostonlocal", "type":"HOST", "url":"http://testserver/api/v1/hosts/2/" }, { "id":3, "name":"127.0.0.[3:4]", "type":"RANGE", "url":"http://testserver/api/v1/hosts/3/" }, { "id":4, "name":"127.0.0.[5:6]", "type":"RANGE", "url":"http://testserver/api/v1/hosts/4/" } ] }
Response JSON Object: response json fields same as in
GET /api/v1/hosts/{id}/
.
-
DELETE
/api/v1/hosts/{id}/
¶ Delete host.
Parameters: - id – id of host.
-
POST
/api/v1/hosts/
¶ Create host.
Request JSON Object: - name (string) – either human-readable name or hostname/IP or range of them (it is depends at context of using this host during playbooks run).
- type (string) – it is
RANGE
if name is range of IPs or hosts, otherwise isHOST
. - vars (object) – dictionary of variables associated with this object. See Variables for details.
Example request:
POST /api/v1/hosts/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript { "name":"038108237241668497-0875926814493907", "type":"HOST", "vars":{ }, }
Results:
{ "id":12, "name":"038108237241668497-0875926814493907", "type":"HOST", "vars":{ }, "url":"http://localhost:8080/api/v1/hosts/12/?format=json" }
Response JSON Object: response json fields same as in
GET /api/v1/hosts/{id}/
.
-
PATCH
/api/v1/hosts/{id}/
¶ Update host. All parameters except id are optional, so you can specify only needed to update. Only name for example.
Parameters: - id – id of host.
Request JSON Object: request json fields same as in
POST /api/v1/hosts/
Example request:
PATCH /api/v1/hosts/12/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript { "name":"038108237241668497-0875926814493907", "type":"HOST", "vars":{ }, }
Results:
{ "id":12, "name":"038108237241668497-0875926814493907", "type":"HOST", "vars":{ }, "url":"http://localhost:8080/api/v1/hosts/12/?format=json" }
Response JSON Object: response json fields same as in
GET /api/v1/hosts/{id}/
.
Groups¶
-
GET
/api/v1/groups/{id}/
¶ Get details about one group.
Parameters: - id – id of group.
Example request:
GET /api/v1/groups/12/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ "id":1, "name":"Group1", "hosts":[ { "id":41, "name":"127.0.0.2", "type":"HOST", "url":"http://localhost:8080/api/v1/hosts/41/" }, { "id":42, "name":"192.168.0.[1-10]", "type":"RANGE", "url":"http://localhost:8080/api/v1/hosts/42/" } ], "groups":[ ], "vars":{ }, "children":false, "url":"http://localhost:8080/api/v1/groups/1/" }
Response JSON Object: - id (number) – id of group.
- name (string) – name of group.
- hosts (array) – list of hosts in group if
children
isfalse
, otherwise empty. See Hosts for fields explanation. - groups (array) – list of subgroups in group if
children
istrue
, otherwise empty. - vars (object) – dictionary of variables associated with this object. See Variables for details.
- children (boolean) – either this group of subgroups or group of hosts.
- url (string) – url to this specific group.
-
GET
/api/v1/groups/
¶ List of groups. Pagination is used for this list.
Query Parameters: - id – id of group if we want to filter by it.
- name – name of group if we want to filter by it.
- id__not – id of group, which we want to filter out.
- name__not – name of group, which we want to filter out.
Example request:
GET /api/v1/groups/?name__not=web-servers HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ "count":2, "next":null, "previous":null, "results":[ { "id":1, "name":"Group1", "children":false, "url":"http://localhost:8080/api/v1/groups/1/" }, { "id":2, "name":"Group2", "children":true, "url":"http://localhost:8080/api/v1/groups/2/" } ] }
Response JSON Object: response json fields same as in
GET /api/v1/groups/{id}/
.
-
DELETE
/api/v1/groups/{id}/
¶ Delete group.
Parameters: - id – id of group.
-
POST
/api/v1/groups/
¶ Create group.
Request JSON Object: - name (string) – name of new group.
- children (boolean) – either this group of subgroups or group of hosts.
- vars (object) – dictionary of variables associated with this object. See Variables for details.
Example request:
POST /api/v1/groups/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript { "name":"SomeGroup", "children":true, "vars":{ } }
Results:
{ "id":3, "name":"SomeGroup", "hosts":[ ], "groups":[ ], "vars":{ }, "children":true, "url":"http://localhost:8080/api/v1/groups/3/" }
Response JSON Object: response json fields same as in
GET /api/v1/groups/{id}/
.
-
PATCH
/api/v1/groups/{id}/
¶ Update group. All parameters except id are optional, so you can specify only needed to update. Only name for example.
Parameters: - id – id of group.
Request JSON Object: request json fields same as in
POST /api/v1/groups/
Example request:
PATCH /api/v1/groups/3/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript { "name":"SomeGroupChanged", "children":true, "vars":{ } }
Results:
{ "id":3, "name":"SomeGroupChanged", "hosts":[ ], "groups":[ ], "vars":{ }, "children":true, "url":"http://localhost:8080/api/v1/groups/3/" }
Response JSON Object: response json fields same as in
GET /api/v1/groups/{id}/
.
-
POST
/api/v1/groups/{group_id}/hosts/
¶ Add hosts to group. See Sublists for details.
Status Codes: - 409 Conflict – attempt work with hosts list of children
group (
children=true
). Such kind of groups only for store other groups in there.
- 409 Conflict – attempt work with hosts list of children
group (
-
PUT
/api/v1/groups/{group_id}/hosts/
¶ Replace sublist of hosts with new one. See Sublists for details.
Status Codes: status codes same as in
POST /api/v1/groups/{group_id}/hosts/
.
-
DELETE
/api/v1/groups/{group_id}/hosts/
¶ Remove those hosts from group. See Sublists for details.
Status Codes: status codes same as in
POST /api/v1/groups/{group_id}/hosts/
.
-
POST
/api/v1/groups/{group_id}/groups/
¶ Add subgroups to group. See Sublists for details.
Status Codes: - 409 Conflict – attempt work with group list of not children group
(
children=false
). Such kind of groups only for store hosts in there.
- 409 Conflict – attempt work with group list of not children group
(
-
PUT
/api/v1/groups/{group_id}/groups/
¶ Replace sublist of subgroups with new one. See Sublists for details.
Status Codes: status codes same as in
POST /api/v1/groups/{group_id}/groups/
.
-
DELETE
/api/v1/groups/{group_id}/groups/
¶ Remove those subgroups from group. See Sublists for details.
Status Codes: status codes same as in
POST /api/v1/groups/{group_id}/groups/
.
Inventories¶
-
GET
/api/v1/inventories/{id}/
¶ Get details about one inventory.
Parameters: - id – id of inventory.
Example request:
GET /api/v1/inventories/8/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ "id":8, "name":"Inventory1", "hosts":[ ], "groups":[ ], "vars":{ }, "url":"http://localhost:8080/api/v1/inventories/8/" }
Response JSON Object: - id (number) – id of inventory.
- name (string) – name of inventory.
- hosts (array) – list of hosts in inventory. See Hosts for fields explanation.
- groups (array) – list of groups in inventory. See Groups for fields explanation.
- vars (object) – dictionary of variables associated with this object. See Variables for details.
- url (string) – url to this specific inventory.
-
GET
/api/v1/inventories/
¶ List of inventories. Pagination is used for this list.
Query Parameters: - id – id of inventory if we want to filter by it.
- name – name of inventory if we want to filter by it.
- id__not – id of inventory, which we want to filter out.
- name__not – name of inventory, which we want to filter out.
Example request:
GET /api/v1/inventories/?name__not=production HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ "count":1, "next":null, "previous":null, "results":[ { "id":8, "name":"Inventory1", "url":"http://localhost:8080/api/v1/inventories/8/" } ] }
Response JSON Object: response json fields same as in
GET /api/v1/inventories/{id}/
.
-
DELETE
/api/v1/inventories/{id}/
¶ Delete inventory.
Parameters: - id – id of inventory.
-
POST
/api/v1/inventories/
¶ Create inventory.
Request JSON Object: - name (string) – name of new inventory.
- vars (object) – dictionary of variables associated with this object. See Variables for details.
Example request:
POST /api/v1/inventories/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript { "name":"Test servers", "vars":{ } }
Results:
{ "id":9, "name":"Test servers", "hosts":[ ], "groups":[ ], "vars":{ }, "url":"http://localhost:8080/api/v1/inventories/9/" }
Response JSON Object: response json fields same as in
GET /api/v1/inventories/{id}/
.
-
PATCH
/api/v1/inventories/{id}/
¶ Update inventory. All parameters except id are optional, so you can specify only needed to update. Only name for example.
Parameters: - id – id of inventory.
Request JSON Object: request json fields same as in
POST /api/v1/inventories/
Example request:
PATCH /api/v1/inventories/9/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript { "name":"Test servers", "vars":{ } }
Results:
{ "id":9, "name":"Test servers", "hosts":[ ], "groups":[ ], "vars":{ }, "url":"http://localhost:8080/api/v1/inventories/9/" }
Response JSON Object: response json fields same as in
GET /api/v1/inventories/{id}/
.
-
PUT
/api/v1/inventories/{inventory_id}/hosts/
¶ Replace sublist of hosts with new one. See Sublists for details.
-
DELETE
/api/v1/inventories/{inventory_id}/hosts/
¶ Remove those hosts from inventory. See Sublists for details.
Projects¶
-
GET
/api/v1/projects/{id}/
¶ Get details about project.
Parameters: - id – id of project.
Example request:
GET /api/v1/projects/5/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ "id":7, "name":"project_pooh", "status":"WAIT_SYNC", "repository":"git@ex.us:dir/rep1.git", "hosts":[ ], "groups":[ ], "inventories":[ ], "vars":{ "repo_password":"forgetit", "repo_type":"GIT" }, "url":"http://localhost:8080/api/v1/projects/7/" }
Response JSON Object: - id (number) – id of project.
- name (string) – name of project.
- repository (string) – URL of repository (repo-specific URL).
For
TAR
it is just HTTP-link to archive. - status (string) – current state of project. Possible values are:
NEW
- newly created project,WAIT_SYNC
- repository synchronization scheduled but not yet started to perform,SYNC
- synchronization in progress,ERROR
- synchronization failed (cvs failure? incorrect credentials?),OK
- project is synchronized. - hosts (array) – list of hosts in project. See Hosts for fields explanation.
- groups (array) – list of groups in project. See Groups for fields explanation.
- vars (object) – dictionary of variables associated with this
object. See Variables for details. In this special case always exists
variables
repo_password
to store password for repository andrepo_type
to store type of repository. Currently implemented types areGIT
for Git repositories. AndTAR
for uploading tar archive with project files. - url (string) – url to this specific inventory.
-
GET
/api/v1/projects/
¶ List of projects. Pagination is used for this list.
Query Parameters: - id – id of project if we want to filter by it.
- name – name of project if we want to filter by it.
- id__not – id of project, which we want to filter out.
- name__not – name of project, which we want to filter out.
- status –
status
of projects to show in list - status__not –
status
of projects to not show in list
Example request:
GET /api/v1/projects/?status__not=SYNC HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ "count":2, "next":null, "previous":null, "results":[ { "id":7, "name":"project_pooh", "status":"WAIT_SYNC", "type":"GIT", "url":"http://localhost:8080/api/v1/projects/7/" }, { "id":8, "name":"project_tigger", "status":"WAIT_SYNC", "type":"GIT", "url":"http://localhost:8080/api/v1/projects/8/" } ] }
Response JSON Object: - type (string) – special shortcut to var
repo_type
. Details about that var and other json fields of response you can see atGET /api/v1/projects/{id}/
-
DELETE
/api/v1/projects/{id}/
¶ Delete project.
Parameters: - id – id of project.
-
POST
/api/v1/projects/
¶ Create project. Operation automatically triggers synchronization. Details about what it is you can see in description
POST /api/v1/projects/{id}/sync/
Request JSON Object: - name (string) – name of new project.
- vars (object) – dictionary of variables associated with this
object. See Variables for details. In this special case always exists
variables
repo_password
to store password for repository andrepo_type
to store type of repository. Currently implemented types areGIT
for Git repositories. AndTAR
for uploading tar archive with project files. - repository (string) – URL of repository (repo-specific URL).
For
TAR
it is just HTTP-link to archive.
Example request:
POST /api/v1/projects/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript { "name":"project_owl", "repository":"somewhere-in-emptiness", "vars":{ "repo_type":"TAR", "repo_password":"" } }
Results:
{ "id":9, "name":"project_owl", "status":"WAIT_SYNC", "repository":"somewhere-in-emptiness", "hosts":[ ], "groups":[ ], "inventories":[ ], "vars":{ "repo_password":"", "repo_type":"TAR" }, "url":"http://localhost:8080/api/v1/projects/9/" }
Response JSON Object: response json fields same as in
GET /api/v1/projects/{id}/
.
-
PATCH
/api/v1/projects/{id}/
¶ Update project. Operation does not start synchronization again. If you want synchronize, you must do it by using
POST /api/v1/projects/{id}/sync/
All parameters except id are optional, so you can specify only needed to update. Only name for example.Parameters: - id – id of project.
Request JSON Object: request json fields same as in
POST /api/v1/projects/
Example request:
PATCH /api/v1/projects/9/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript { "name":"project_owl", "repository":"somewhere-in-emptiness", "vars":{ "repo_type":"TAR", "repo_password":"" } }
Results:
{ "id":9, "name":"project_owl", "status":"WAIT_SYNC", "repository":"somewhere-in-emptiness", "hosts":[ ], "groups":[ ], "inventories":[ ], "vars":{ "repo_password":"", "repo_type":"TAR" }, "url":"http://localhost:8080/api/v1/projects/9/" }
Response JSON Object: response json fields same as in
GET /api/v1/projects/{id}/
.
-
PUT
/api/v1/projects/{project_id}/hosts/
¶ Replace sublist of hosts with new one. See Sublists for details.
-
DELETE
/api/v1/projects/{project_id}/hosts/
¶ Remove those hosts from project. See Sublists for details.
-
PUT
/api/v1/projects/{project_id}/groups/
¶ Replace sublist of groups with new one. See Sublists for details.
-
DELETE
/api/v1/projects/{project_id}/groups/
¶ Remove those groups from project. See Sublists for details.
-
POST
/api/v1/projects/{project_id}/inventories/
¶ Add inventories to project. See Sublists for details.
-
PUT
/api/v1/projects/{project_id}/inventories/
¶ Replace sublist of inventories with new one. See Sublists for details.
-
DELETE
/api/v1/projects/{project_id}/inventories/
¶ Remove those inventories from project. See Sublists for details.
-
GET
/api/v1/projects/supported-repos/
¶ Returns list of supported repository types.
Results:
[ "TAR", "GIT" ]
-
POST
/api/v1/projects/{id}/sync/
¶ Starts synchronization. During that process project files uploading from repository. Concrete details of process highly depends on project type. For
GIT
isgit pull
, forTAR
it just downloading archive from URL again and unpacking it with rewrite of old files. And so on.Parameters: - id – id of project.
Results:
{ "detail":"Sync with git@ex.us:dir/rep1.git." }
-
POST
/api/v1/projects/{id}/execute-playbook/
¶ Execute ansible playbook. Returns history id for watching execution process.
Parameters: - id – id of project.
Request JSON Object: - inventory (number) – inventory to execute playbook at.
- playbook (string) – playbook to execute.
- * – any number parameters with any name and string or number type. All
those parameters just passes as additional command line arguments to
ansible-playbook
utility during execution, so you can use this feature to widely customize of ansible behaviour. For anykey:value
in command line will be--key value
. If you want only key without a value (--become
option for example), just passnull
as value.
Example request:
POST /api/v1/projects/1/execute-playbook/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript { "inventory": 13, "playbook": "main.yml" "become": null, "su-user": "rootburger" }
Results:
{ "detail":"Started at inventory 13.", "history_id": 87 }
-
POST
/api/v1/projects/{id}/execute-module/
¶ Execute ansible module. Just like running
ansible -m {something}
by hands. You can quickly do something with ansible without boring and time consuming work with playbooks etc.Request JSON Object: - inventory (number) – inventory to execute at.
- module (string) – name of module (like
ping
,shell
and so on). You can use any of modules available in ansible. - group (string) – to which group in your inventory it must be executed.
Use
all
for all hosts in inventory. - args (string) – which args must be passed to module. Just raw string
with arguments. You can specify here contains of
args
option. For examplels -la
forshell
module. - * – any number parameters with any name and string or number type. All
those parameters just passes as additional command line arguments to
ansible-playbook
utility during execution, so you can use this feature to widely customize of ansible behaviour. For anykey:value
in command line will be--key value
. If you want only key without a value (--become
option for example), just passnull
as value.
Example request:
POST /api/v1/projects/1/execute-module/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript { "inventory":3, "module":"shell", "group":"all", "args":"ls -la" }
Results:
{ "detail":"Started at inventory 3.", "history_id": 87 }
Tasks¶
-
GET
/api/v1/tasks/{id}/
¶ Get details about task.
Parameters: - id – id of task.
Example request:
GET /api/v1/tasks/5/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ "id":5, "name":"Ruin my environment", "playbook":"ruin_my_env.yml", "project":13 "url":"http://localhost:8080/api/v1/tasks/5/" }
Response JSON Object: - id (number) – id of task.
- name (string) – name of task.
- playbook (string) – playbook file to run within this task.
- project (number) – id of project, to which this task belongs.
- url (string) – url to this specific task.
-
GET
/api/v1/tasks/
¶ List tasks. Pagination is used for this list.
Query Parameters: - id – id of task if we want to filter by it.
- name – name of task if we want to filter by it.
- id__not – id of task, which we want to filter out.
- name__not – name of task, which we want to filter out.
- playbook – filter by name of playbook.
- project – filter by id of project.
Example request:
GET /api/v1/tasks/?project=13 HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ "count":1, "next":null, "previous":null, "results":[ { "id":5, "name":"Ruin my environment", "url":"http://localhost:8080/api/v1/tasks/5/" } ] }
Periodic tasks¶
-
GET
/api/v1/periodic-tasks/{id}/
¶ Get details about periodic task.
Parameters: - id – id of periodic task.
Example request:
GET /api/v1/periodic-tasks/10/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ "id":10, "type":"CRONTAB", "schedule":"60* */2 sun,fri 1-15 *", "mode":"collect_data.yml", "kind":"PLAYBOOK", "project":7, "inventory":8, "vars":{ }, "url":"http://127.0.0.1:8080/api/v1/periodic-tasks/10/?format=json" }
Response JSON Object: - id (number) – id of periodic task.
- type (string) – type of periodic task. Either
INTERVAL
for tasks that runs every N seconds orCRONTAB
for tasks, which runs according by more complex rules. According to thatschedule
field will be interpreted as integer - number of seconds between runs. Or string in cron format with one small exception - Polemarch expect string without year, because years is not supported. You can easily find documentation for cron format in web. Like those, for example: https://linux.die.net/man/5/crontab and http://www.nncron.ru/help/EN/working/cron-format.htm - schedule (string) – string with integer value or string in
cron format, what depends on
type
value. Look attype
description for details. - mode (string) – playbook or module to run periodically.
- kind (string) – either this task is playbook run (
PLAYBOOK
) or module run (MODULE
). - project (number) – id of project which this task belongs to.
- inventory (number) – id of inventory for which must execute_playbook playbook.
- vars (object) – those vars have special meaning. All those
parameters just passes as additional command line arguments to
ansible-playbook
utility during execution, so you can use this feature to widely customize of ansible behaviour. For anykey:value
in command line will be--key value
. If you want only key without a value (--become
option for example), just passnull
as value. In all other aspects this field works like usualvars
: dictionary of variables associated with this object. See Variables for details. - url (string) – url to this specific periodic task.
-
GET
/api/v1/periodic-tasks/
¶ List of periodic tasks. Pagination is used for this list.
Query Parameters: - id – id of template if we want to filter by it.
- id__not – id of template, which we want to filter out.
- mode – filter by playbook or module name.
- kind – filter by kind of task.
- type – filter by
type
. - project – filter by project id.
Example request:
GET /api/v1/periodic-tasks/?project=7 HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ "count":2, "next":null, "previous":null, "results":[ { "id":10, "type":"INTERVAL", "schedule":"60", "mode":"collect_data.yml", "kind":"PLAYBOOK", "inventory":8, "vars":{ }, "url":"http://127.0.0.1:8080/api/v1/periodic-tasks/10/?format=json" }, { "id":11, "type":"CRONTAB", "schedule":"* */2 sun,fri 1-15 *", "mode":"do_greatest_evil.yml", "kind":"PLAYBOOK", "inventory":8, "vars":{ }, "url":"http://127.0.0.1:8080/api/v1/periodic-tasks/11/?format=json" } ] }
Response JSON Object: response json fields same as in
GET /api/v1/periodic-tasks/{id}/
.
-
DELETE
/api/v1/periodic-tasks/{id}/
¶ Delete periodic task.
Parameters: - id – id of periodic task.
-
POST
/api/v1/periodic-tasks/
¶ Create periodic task
Request JSON Object: - type (string) – type of periodic task. Either
INTERVAL
for tasks that runs every N seconds orCRONTAB
for tasks, which runs according by more complex rules. According to thatschedule
field will be interpreted as integer - number of seconds between runs. Or string in cron format with one small exception - Polemarch expect string without year, because years is not supported. You can easily find documentation for cron format in web. Like those, for example: https://linux.die.net/man/5/crontab and http://www.nncron.ru/help/EN/working/cron-format.htm - schedule (string) – string with integer value or string in
cron format, what depends on
type
value. Look attype
description for details. - mode (string) – playbook or module to run periodically. Depends on value
of
kind
field. - kind (string) – Optional argument. Either this task is playbook run
(
PLAYBOOK
) or module run (MODULE
). If omitted, will be default -PLAYBOOK
. Module tasks also requires two variables for execution:args
for module-specific args (can be omitted or empty string) andgroup
to specify for which group in inventory module must run. If you forget to specify group, your task will fail. - project (number) – id of project, which task belongs to.
- inventory (number) – id of inventory to run playbook on.
- vars (object) – those vars have special meaning. All those
parameters just passes as additional command line arguments to
ansible-playbook
utility during execution, so you can use this feature to widely customize of ansible behaviour. For anykey:value
in command line will be--key value
. If you want only key without a value (--become
option for example), just passnull
as value. In all other aspects this field works like usualvars
: dictionary of variables associated with this object. See Variables for details.
Example request:
POST /api/v1/periodic-tasks/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript { "type": "INTERVAL", "schedule": "25", "mode": "touch_the_clouds.yml", "project": 7, "inventory": 8 "vars":{ }, }
Results:
{ "id": 14, "type": "INTERVAL", "schedule": "25", "mode": "touch_the_clouds.yml", "kind": "PLAYBOOK", "project": 7, "inventory": 8, "vars":{ }, "url": "http://127.0.0.1:8080/api/v1/periodic-tasks/14/?format=api" }
Response JSON Object: response json fields same as in
GET /api/v1/periodic-tasks/{id}/
.- type (string) – type of periodic task. Either
-
PATCH
/api/v1/periodic-tasks/{id}/
¶ Update periodic task. All parameters except id are optional, so you can specify only needed to update. Only name for example.
Parameters: - id – id of periodic task.
Request JSON Object: request json fields same as in
POST /api/v1/periodic-tasks/
Example request:
PATCH /api/v1/periodic-tasks/14/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript { "type": "INTERVAL", "schedule": "25", "mode": "touch_the_clouds.yml", "project": 7, "inventory": 8 }
Results:
{ "id": 14, "type": "INTERVAL", "schedule": "25", "mode": "touch_the_clouds.yml", "kind": "PLAYBOOK", "project": 7, "inventory": 8, "url": "http://127.0.0.1:8080/api/v1/periodic-tasks/14/?format=api" }
Response JSON Object: response json fields same as in
GET /api/v1/periodic-tasks/{id}/
.
Templates¶
-
GET
/api/v1/templates/{id}/
¶ Get template with details.
Parameters: - id – id of template.
Example request:
GET /api/v1/templates/1/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ "id": 1, "name": "test_tmplt", "kind": "Task", "data": { "playbook": "test.yml", "vars": { "connection": "paramiko" } } }
Response JSON Object: - id (number) – id of template.
- name (string) – name of template.
- kind (string) – Kind of template. Supported kinds
could see in
GET /api/v1/templates/supported-kinds/
. - data (string) – JSON structure of template. Supported
fields could see in
GET /api/v1/templates/supported-kinds/
.
-
GET
/api/v1/templates/
¶ Get list of templates. Pagination is used for this list.
Query Parameters: - id – id of project if we want to filter by it.
- id__not – id of project, which we want to filter out.
- name – filter by name.
- name__not – filter by name, which we want to filter out.
- kind – filter by
kind
. - project – filter by
project
. - inventory – filter by
inventory
.
Example request:
GET /api/v1/templates/?kind=Task HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ "count": 1, "next": null, "previous": null, "results": [ { "id": 1, "name": "test_tmplt", "kind": "Task" } ] }
Response JSON Object: response json fields same as in
GET /api/v1/templates/{id}/
.
-
DELETE
/api/v1/templates/{id}/
¶ Delete periodic task.
Parameters: - id – id of periodic task.
-
POST
/api/v1/templates/
¶ Create template
Request JSON Object: - kind (string) – Kind of template. Supported kinds
could see in
GET /api/v1/templates/supported-kinds/
. - data (string) – JSON structure of template. Supported
fields could see in
GET /api/v1/templates/supported-kinds/
. - name (string) – template name.
Example request:
POST /api/v1/templates/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript { "name": "test", "kind": "Task", "data": { "playbook": "test.yml", "vars": { "connection": "paramiko" } } }
Results:
{ "id": 2, "name": "test", "kind": "Task", "data": { "playbook": "test.yml", "vars": { "connection": "paramiko" } } }
Response JSON Object: response json fields same as in
GET /api/v1/templates/{id}/
.- kind (string) – Kind of template. Supported kinds
could see in
-
PATCH
/api/v1/templates/{id}/
¶ Update template. If update data, should send full template data. All parameters except id are optional, so you can specify only needed to update. Only name for example.
Parameters: - id – id of template.
Request JSON Object: request json fields same as in
POST /api/v1/templates/
Example request:
PATCH /api/v1/templates/2/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript { "name": "test_new_name" }
Results:
{ "id": 2, "name": "test_new_name", "kind": "Task", "data": { "playbook": "test.yml", "vars": { "connection": "paramiko" } } }
Response JSON Object: response json fields same as in
GET /api/v1/templates/{id}/
.
-
GET
/api/v1/templates/supported-kinds/
¶ List of supported kinds.|pagination_def|
Example request:
GET /api/v1/history/supported-kinds/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ "Task": [ "playbook", "vars", "inventory", "project" ], "Host": [ "name", "vars" ], "PeriodicTask": [ "playbook", "vars", "inventory", "project", "type", "name", "schedule" ], "Group": [ "name", "vars", "children" ] }
History records¶
-
GET
/api/v1/history/{id}/
¶ Get details about one history record.
Parameters: - id – id of history record.
Example request:
GET /api/v1/history/1/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ "id":1, "project":2, "mode":"task.yml", "status":"OK", "kind": "PLAYBOOK", "start_time":"2017-07-02T12:48:11.922761Z", "stop_time":"2017-07-02T13:48:11.922777Z", "raw_inventory":"inventory", "raw_args": "ansible-playbook main.yml -i /tmp/tmpvMIwMg -v", "raw_stdout":"text", "initiator": 1, "initiator_type": "users" }
Response JSON Object: - id (number) – id of history record.
- project (number) – id of project, which record belongs to.
- mode (string) – name of executed playbook or module.
- kind (string) – either was run of
ansible-playbook
(PLAYBOOK
) oransible
(MODULE
). - status (string) – either
DELAY
,OK
,INTERRUPTED
,RUN
,OFFLINE
orERROR
, which indicates different results of execution (scheduled for run, good, interrupted by user, currently running, can’t connect to node, failure). - start_time (string) – time, when playbook execution was started.
- stop_time (string) – time, when playbook execution was ended (normally or not)
- raw_inventory (string) – Ansible inventory, which used for execution. It is generates from on of Polemarch’s Inventories
- raw_args (string) – ansible command line during execution.
- raw_stdout (string) – what Ansible wrote to stdout and stderr during
execution. The size is limited to 10M characters. Full output
in
GET /api/v1/history/{id}/raw/
. - initiator (number) – initiator id.
- initiator_type (string) – initiator type like in api url.
- url (string) – url to this specific history record.
-
POST
/api/v1/history/{id}/cancel/
¶ Cancel currently executed task.
Parameters: - id – id of history record.
Example request:
POST /api/v1/history/1/cancel/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ "detail": "Task canceled: 1" }
-
GET
/api/v1/history/{id}/raw/
¶ Get full output of executed task.
Parameters: - id – id of history record.
Query Parameters: - color – Default is
no
. Ifyes
you will get output with ANSI Esc color codes printed by Ansible in addition to text itself.
Example request:
GET /api/v1/history/1/raw/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
PLAY [all] ********************************************************************* TASK [Gathering Facts] ********************************************************* ok: [chat.vstconsulting.net] ok: [pipc.vst.lan] ok: [git.vst.lan] ok: [git-ci-2] ok: [git-ci-1] ok: [redmine.vst.lan] ok: [test2.vst.lan] ok: [test.vst.lan] ......
-
GET
/api/v1/history/{id}/lines/
¶ List of history record lines. Pagination is used for this list.
Query Parameters: - after – filter lines to return lines after this number.
- before – filter lines to return lines before this number.
Example request:
GET /api/v1/history/1/lines/?after=2 HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ "count": 2, "next": null, "previous": null, "results": [ { "line_number": 4, "line": "" }, { "line_number": 3, "line": "ERROR! the playbook: /home/centos/test/polemarch/projects/1/test.yml could not be found" } ] }
-
GET
/api/v1/history/
¶ List of history records. Pagination is used for this list.
Query Parameters: - id – id of inventory if we want to filter by it.
- id__not – id of inventory, which we want to filter out.
- start_time__gt – filter records whose
start_time
greater than specified. - stop_time__gt – filter records whose
stop_time
greater than specified. - start_time__lt – filter records whose
start_time
less than specified. - stop_time__lt – filter records whose
stop_time
less than specified. - start_time__gte – filter records whose
start_time
greater or equal to specified. - stop_time__gte – filter records whose
stop_time
greater or equal to specified. - start_time__lte – filter records whose
start_time
less or equal to specified. - stop_time__lte – filter records whose
stop_time
less or equal to specified. - mode – filter by
mode
. - kind – filter by
kind
. - project – filter by
project
. - status – filter by
status
. - start_time – get records only with
start_time
equal to specified. - stop_time – get records only with
stop_time
equal to specified.
Example request:
GET /api/v1/history/?start_time__gte=2017-06-01T01:48:11.923896Z HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ "count":2, "next":null, "previous":null, "results":[ { "id": 121, "project": 3, "mode": "main.yml", "kind": "PLAYBOOK", "status": "OK", "start_time": "2017-07-24T06:39:52.052504Z", "stop_time": "2017-07-24T06:41:06.521813Z", "url": "http://localhost:8000/api/v1/history/121/" }, { "id": 118, "project": null, "mode": "ping", "kind": "MODULE", "status": "OK", "start_time": "2017-07-24T06:27:40.481588Z", "stop_time": "2017-07-24T06:27:42.499873Z", "url": "http://localhost:8000/api/v1/history/118/" } ] }
Response JSON Object: response json fields same as in
GET /api/v1/history/{id}/
.
-
DELETE
/api/v1/history/{id}/
¶ Delete history record.
Parameters: - id – id of record.
-
GET
/api/v1/history/{id}/facts/
¶ Get facts gathered during execution of
setup
module.Parameters: - id – id of history record.
Example request:
GET /api/v1/history/1/facts/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ "172.16.1.29":{ "status":"SUCCESS", "ansible_facts":{ "ansible_memfree_mb":526 }, "changed":false }, "172.16.1.31":{ "status":"SUCCESS", "ansible_facts":{ "ansible_memfree_mb":736 }, "changed":false }, "172.16.1.30":{ "status":"UNREACHABLE!", "changed":false, "msg":"Failed to connect to the host via ssh: ssh: connect to host 172.16.1.30 port 22: No route to host\r\n", "unreachable":true }, "172.16.1.32":{ "status":"FAILED!", "changed":false, "failed":true, "module_stderr":"Shared connection to 172.16.1.32 closed.\r\n", "module_stdout":"/bin/sh: /usr/bin/python: No such file or directory\r\n", "msg":"MODULE FAILURE" } }
Status Codes: - 200 OK – no error
- 404 Not Found – there is no facts. Either incorrect history id or kind not
MODULE
and/or module is notsetup
. Facts can be gathered only by runningsetup
module. SeePOST /api/v1/projects/{id}/execute-module/
for details about modules run. - 424 Failed Dependency – facts still not ready because module is currently running or only scheduled for run.
Ansible¶
-
GET
/api/v1/ansible/
¶ Get list of available methods in that category. All methods under /ansible/ designed to provide information about ansible installation which Polemarch is currently using.
Example request:
GET /api/v1/ansible/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ "cli-reference": "http://localhost:8000/api/v1/ansible/cli_reference/", "modules": "http://localhost:8000/api/v1/ansible/modules/" }
-
GET
/api/v1/ansible/cli_reference/
¶ Get list of available ansible command line tools arguments with their type and hint.
Query Parameters: - filter – filter by tool, for which you want get help (either ansible or ansible-playbook).
Example request:
GET /api/v1/ansible/cli_reference/?filter=ansible HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ "ansible": { "extra-vars": { "type": "text", "help": "set additional variables as key=value or YAML/JSON" }, "help": { "type": "boolean", "help": "show this help message and exit" }, // there is much more arguments to type it here // ... } }
-
GET
/api/v1/ansible/modules/
¶ Get list of installed ansible modules.
Query Parameters: - filter – filter to search by module name. It is Python regular expression.
Example request:
GET /api/v1/ansible/modules/?filter=\.git HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
[ "extras.source_control.git_config", "extras.source_control.github_release", "extras.source_control.github_hooks", "extras.source_control.gitlab_user", "extras.source_control.github_key", "extras.source_control.gitlab_group", "extras.source_control.gitlab_project", "core.source_control.git" ]
Variables¶
Hosts, groups, inventories, projects in Polemarch may have variables associated with them. Usually (with one exception - variables for additional repository data in Projects) those variables passes to Ansible to somehow customize his behaviour or playbook logic. In all this kinds of objects variables works in same way, so here additional chapter which describes their behaviour abstracting from details related to every concrete type of object.
In JSON responses related to those objects variables are placed in field
vars
. This field is just key-value dictionary of existent variables for
object. It can be saved in POST
and PATCH
request completely
overwriting previous dictionary.
It can be represented in such more formal way:
-
GET
/api/v1/{object_kind}/{object_id}
¶ Get details about one object.
Parameters: - id – id of this object.
Example request:
GET /api/v1/hosts/12/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ // object-special data goes here "vars":{ "string_variable1": "some_string", "integer_variable2": 12, "float_variable3": 0.3 } }
Response JSON Object: - vars (object) – dictionary of variables for this object.
-
PATCH
/api/v1/{object_kind}/{object_id}
¶ Update object.
Parameters: - id – id of object.
Request JSON Object: - vars (object) – dictionary of variables to save in object. It is completely rewrites old dictionary.
Example request:
PATCH /api/v1/hosts/12/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript { // there is may be other object-related stuff "vars":{ "string_variable1": "some_string", "integer_variable2": 12, "float_variable3": 0.3 } }
Results:
{ // object-special data goes here "vars":{ "string_variable1": "some_string", "integer_variable2": 12, "float_variable3": 0.3 }, }
Also for all previously enumerated kinds of objects (which support variables) there is filtering by variables possible in get requests like this:
-
GET
/api/v1/{object_kind}/
¶ Get list of objects. Pagination is used for this list.
Query Parameters: - variables – filter objects by variables and their values. Variables
specified as list using
,
as separator for every list item and:
as separator for key and value. Likevar1:value,var2:value,var3:12
.
Example request:
GET /api/v1/groups/?variables=ansible_port:222,ansible_user:one HTTP/1.1 Host: example.com Accept: application/json, text/javascript
- variables – filter objects by variables and their values. Variables
specified as list using
Sublists¶
Many of objects types in Polemarch can contain collections of other objects. For example Group can contain sublist of Hosts included in this group. Because all of those sublists base on the same logic, we documenting here general principles of this logic. Its made in order to not duplicate this information for every method of such kind.
Here the list of those methods:
Groups:
POST /api/v1/groups/{group_id}/hosts/
PUT /api/v1/groups/{group_id}/hosts/
DELETE /api/v1/groups/{group_id}/hosts/
POST /api/v1/groups/{group_id}/groups/
PUT /api/v1/groups/{group_id}/groups/
DELETE /api/v1/groups/{group_id}/groups/
Inventories:
POST /api/v1/inventories/{inventory_id}/hosts/
PUT /api/v1/inventories/{inventory_id}/hosts/
DELETE /api/v1/inventories/{inventory_id}/hosts/
POST /api/v1/inventories/{inventory_id}/groups/
PUT /api/v1/inventories/{inventory_id}/groups/
DELETE /api/v1/inventories/{inventory_id}/groups/
Projects:
POST /api/v1/projects/{project_id}/hosts/
PUT /api/v1/projects/{project_id}/hosts/
DELETE /api/v1/projects/{project_id}/hosts/
POST /api/v1/projects/{project_id}/groups/
PUT /api/v1/projects/{project_id}/groups/
DELETE /api/v1/projects/{project_id}/groups/
POST /api/v1/projects/{project_id}/inventories/
PUT /api/v1/projects/{project_id}/inventories/
DELETE /api/v1/projects/{project_id}/inventories/
As you can see there is plenty of urls and for every url post
, put
and
delete
methods are present. They all takes list of IDs in json request
body, but do different things with those IDs. put
methods completely
rewrite sublist with new list. post
method just append new IDs to already
existent. delete
method removes specified IDs from existent list.
All of those methods returns such json as result:
{
"not_found":0,
"operated":2,
"total":2,
"failed_list": []
}
There not_found
counter for items, which can’t be processed for some
reason. operated
for processed successfully. And total
is number of
elements that was in initial request. If some items not operated successfully,
failed_list will be list of them. Otherwise just empty list.
IDs always for object kind, which must be stored in this sublist. For example,
for groups/{group_id}/hosts/
it must be ids of existent hosts. If host with
id from list not exist method still return 200 OK
, but result stats will
reflect that fact, that one of the ids can’t be processed successfully.
To clarify information above here is example detailed structured explanation (with request and response examples) for those methods:
-
ANY
/api/v1/{object_kind}/{object_id}/{sublist_kind}/
¶ Operate with sublist of objects for some concrete object.
post
- append new objects to already existent sublist.delete
- removes those objects from existent sublist.put
- rewrite sublist with this one.
Parameters: - object_kind – kind of object, whose sublist we modify.
- object_id – id of concrete object, whose sublist we modify.
- sublist_kind – kind of objects, stored in sublist
Request JSON Array of Objects: - Ids – Ids of objects, which we must add/remove/replace in sublist.
Example request:
POST /api/v1/groups/1/hosts/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript [2, 3]
{ "not_found":0, "operated":2, "total":2 }
Response JSON Object: - not_found (number) – count of processed with error (not exists or no access).
- operated (number) – count of processed successfully.
- total (number) – count of all sent ids.
Users¶
-
GET
/api/v1/users/{id}/
¶ Get details about one user.
Parameters: - id – id of user.
Example request:
GET /api/v1/users/3/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ "id":3, "username":"petya", "password":"pbkdf2_sha256$36000$usSWH0uGIPZl$+Xzz3KpJrq8ZP3truExYOe3CjsaIWgOxuN6jIvJ5ZO8=", "is_active":true, "is_staff":false, "first_name":"Petya", "last_name":"Smith", "email":"petyasupermail@example.com", "url":"http://127.0.0.1:8080/api/v1/users/3/" }
Response JSON Object: - id (number) – id of user.
- username (string) – login.
- password (string) – hash of password.
- is_active (boolean) – is account enabled.
- is_staff (boolean) – is it superuser. Superuser have access to all objects/records despite of access rights.
- first_name (string) – name.
- last_name (string) – last name.
- email (string) – email.
- url (string) – url to this specific user.
-
GET
/api/v1/users/
¶ List of users. Pagination is used for this list.
Query Parameters: - id – id of host if we want to filter by it.
- id__not – id of host, which we want to filter out.
- username – filter by login.
- is_active – filter enabled users.
- first_name – filter by name.
- last_name – filter by last name.
- email – filter by email.
Example request:
GET /api/v1/users/?is_active=true HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ "count":2, "next":null, "previous":null, "results":[ { "id":1, "username":"admin", "is_active":true, "url":"http://127.0.0.1:8080/api/v1/users/1/" }, { "id":3, "username":"petya", "is_active":true, "url":"http://127.0.0.1:8080/api/v1/users/3/" } ] }
Response JSON Object: response json fields same as in
GET /api/v1/users/{id}/
.
-
DELETE
/api/v1/users/{id}/
¶ Delete user.
Parameters: - id – id of user.
-
POST
/api/v1/users/
¶ Create user.
Request JSON Object: - username (string) – login.
- password (string) – password.
- is_active (boolean) – is account enabled.
- is_staff (boolean) – is it superuser. Superuser have access to all objects/records despite of access rights.
- first_name (string) – name.
- last_name (string) – last name.
- email (string) – email.
Example request:
POST /api/v1/users/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript { "email":"petyasupermail@example.com", "first_name":"Petya", "last_name":"Smith", "username":"petya", "is_active":"true", "is_staff":"false", "password":"rex" }
Results:
{ "id":3, "username":"petya", "password":"pbkdf2_sha256$36000$usSWH0uGIPZl$+Xzz3KpJrq8ZP3truExYOe3CjsaIWgOxuN6jIvJ5ZO8=", "is_active":true, "is_staff":false, "first_name":"Petya", "last_name":"Smith", "email":"petyasupermail@example.com", "url":"http://127.0.0.1:8080/api/v1/users/3/" }
Response JSON Object: response json fields same as in
GET /api/v1/users/{id}/
.
-
PATCH
/api/v1/users/{id}/
¶ Update user. All parameters except id are optional, so you can specify only needed to update. Only name for example.
Parameters: - id – id of host.
Request JSON Object: request json fields same as in
POST /api/v1/users/
Example request:
PATCH /api/v1/users/3/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript { "email":"petyasupermail@example.com", "first_name":"Petya", "last_name":"Smith", "username":"petya", "is_active":"true", "is_staff":"false", "password":"rex" }
Results:
{ "id":3, "username":"petya", "password":"pbkdf2_sha256$36000$usSWH0uGIPZl$+Xzz3KpJrq8ZP3truExYOe3CjsaIWgOxuN6jIvJ5ZO8=", "is_active":true, "is_staff":false, "first_name":"Petya", "last_name":"Smith", "email":"petyasupermail@example.com", "url":"http://127.0.0.1:8080/api/v1/users/3/" }
Response JSON Object: response json fields same as in
GET /api/v1/users/{id}/
.
Teams (Polemarch+ only)¶
Teams is groups of users to which you can collectively assign rights to objects in ACL system.
-
GET
/api/v1/teams/{id}/
¶ Get details about one team.
Parameters: - id – id of team.
Example request:
GET /api/v1/teams/1/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ "id": 1, "name": "myteam", "users": [ { "id": 1, "username": "admin", "is_active": true, "is_staff": true, "url": "http://localhost:8000/api/v1/users/1/" } ], "users_list": [ 1 ], "owner": { "id": 1, "username": "admin", "is_active": true, "is_staff": true, "url": "http://localhost:8000/api/v1/users/1/" }, "url": "http://localhost:8000/api/v1/teams/1/" }
Response JSON Object:
-
GET
/api/v1/teams/
¶ List of teams. Pagination is used for this list.
Query Parameters: - id – id of team if we want to filter by it.
- name – name of team if we want to filter by it.
- id__not – id of team, which we want to filter out.
- name__not – name of team, which we want to filter out.
Example request:
GET /api/v1/teams/?name__not=outsiders HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ "count": 1, "next": null, "previous": null, "results": [ { "id": 1, "name": "myteam", "url": "http://localhost:8000/api/v1/teams/1/" } ] }
Response JSON Object: response json fields same as in
GET /api/v1/teams/{id}/
.
-
DELETE
/api/v1/teams/{id}/
¶ Delete team.
Parameters: - id – id of team.
-
POST
/api/v1/teams/
¶ Create team.
Request JSON Object: - name (string) – name of new team.
Example request:
POST /api/v1/teams/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript { "name":"another_team" }
Results:
{ "id": 2, "name": "another_team", "users": [], "users_list": [], "owner": { "id": 1, "username": "admin", "is_active": true, "is_staff": true, "url": "http://localhost:8000/api/v1/users/1/" }, "url": "http://localhost:8000/api/v1/teams/2/" }
Response JSON Object: response json fields same as in
GET /api/v1/teams/{id}/
.
-
PATCH
/api/v1/groups/{id}/
¶ Update team. All parameters except id are optional, so you can specify only needed to update. Only name for example.
Parameters: - id – id of team.
Request JSON Object: - name (string) – name of new team.
- users_list (array) – list of users to put in team.
Example request:
PATCH /api/v1/teams/2/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript { "name":"another_team", "users_list": [1, 2] }
Results:
{ "id": 2, "name": "another_team", "users": [ { "id": 1, "username": "admin", "is_active": true, "is_staff": true, "url": "http://localhost:8000/api/v1/users/1/" }, { "id": 2, "username": "max", "is_active": true, "is_staff": true, "url": "http://localhost:8000/api/v1/users/2/" } ], "users_list": [ 1, 2 ], "owner": { "id": 1, "username": "admin", "is_active": true, "is_staff": true, "url": "http://localhost:8000/api/v1/users/1/" }, "url": "http://localhost:8000/api/v1/teams/2/" }
Response JSON Object: response json fields same as in
GET /api/v1/teams/{id}/
.
ACL system (Polemarch+ only)¶
Because Polemarch supports multiple users it have access rights for every kind of objects. Most kinds of objects (if to be precise: Hosts, Groups, Inventories, Projects, Templates ) have owner and set of permissions associated to every instance of such kind. However other objects (if to be precise: History records, Periodic tasks, Tasks) have dependant role from objects listed above, so they does not have their own permissions, but permissions of parent objects is applicable to them. For example to see PeriodicTasks of project you must have access to project itself.
Currently we support such permission levels:
- EXECUTOR - can see object in objects list, view details and execute (in case of object is executable like Template, Inventory or something).
- EDITOR - same as above + right to edit.
- MASTER - same as above + can work with permissions list for this object (add/delete other users and teams).
- OWNER - same as above + ability to change owner.
Warning: if you granting somebody EXECUTOR permission to object, he also automatically get EXECUTOR rights to all other objects, which required to use this one. Example: if you give User1 EDITOR right to Inventory1, he also got EXECUTOR to all hosts and groups, which currently listed in Inventory1.
Also there is two types of users: regular and superuser. Regular users have access only to objects, where they listed in permissions. Superusers have access to all objects in system. See Users for detailed information about user management api.
Polemarch+ have such methods to control ownership and permissions information:
-
GET
/api/v1/{object_kind}/{id}/permissions/
¶ Get permissions to object.
Parameters: - object_kind – Kind of objects to perform operation. It can be
any present objects type in system:
hosts
,groups
,inventories
,projects
,templates
. - id – Id of object.
Results:
[ { "member":1, "role":"EDITOR", "member_type":"user" }, { "member":2, "role":"MASTER", "member_type":"user" } ]
Response JSON Object: - permissions (array) – list of permissions. Permission JSON Object: json fields
same as in
POST /api/v1/{object_kind}/{id}/permissions/
.
- object_kind – Kind of objects to perform operation. It can be
any present objects type in system:
-
POST
/api/v1/{object_kind}/{id}/permissions/
¶ Add those permissions to object.
Parameters: - object_kind – Kind of objects to perform operation. It can be
any present objects type in system:
hosts
,groups
,inventories
,projects
,templates
. - id – Id of object.
Request JSON Array of Objects: - member (number) – id of user or team for which role should applies.
- role (string) – either
EXECUTOR
,EDITOR
orMASTER
. - member_type (string) – either
user
orteam
(how to interpret id)
Example request:
POST /api/v1/hosts/123/permissions/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript [ { "member":1, "role":"EDITOR", "member_type":"user" }, { "member":2, "role":"MASTER", "member_type":"user" } ]
Results:
[ { "member":1, "role":"EDITOR", "member_type":"user" }, { "member":2, "role":"MASTER", "member_type":"user" } ]
Response JSON Object: - permissions (array) – list of actual object permissions after operation. Every permission is same object as in request, so you can look request fields explanation for details.
- object_kind – Kind of objects to perform operation. It can be
any present objects type in system:
-
PUT
/api/v1/{object_kind}/{id}/permissions/
¶ Replace permissions to object with provided.
Parameters: - object_kind – Kind of objects to perform operation. It can be
any present objects type in system:
hosts
,groups
,inventories
,projects
,templates
. - id – Id of object.
Request JSON Object: - permissions (array) – new permissions list. Permission JSON Object: json fields
same as in
POST /api/v1/{object_kind}/{id}/permissions/
.
PUT /api/v1/hosts/123/permissions/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript [ { "member":1, "role":"EDITOR", "member_type":"user" }, { "member":2, "role":"MASTER", "member_type":"user" } ]
Results:
[ { "member":1, "role":"EDITOR", "member_type":"user" }, { "member":2, "role":"MASTER", "member_type":"user" } ]
Response JSON Object: - permissions (array) – list of actual object permissions after operation.
Permission JSON Object: json fields
same as in
POST /api/v1/{object_kind}/{id}/permissions/
.
- object_kind – Kind of objects to perform operation. It can be
any present objects type in system:
-
DELETE
/api/v1/{object_kind}/{id}/permissions/
¶ Remove access to object for users, who listed in json array in body of request.
Parameters: - object_kind – Kind of objects to perform operation. It can be
any present objects type in system:
hosts
,groups
,inventories
,projects
,templates
. - id – Id of object.
Request JSON Object: - permissions (array) – which permissions remove. You can use PUT with
empty list if you want to remove all permissions. Permission JSON Object: json fields
same as in
POST /api/v1/{object_kind}/{id}/permissions/
.
Example request:
DELETE /api/v1/hosts/123/permissions/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript [ { "member":1, "role":"EDITOR", "member_type":"user" }, { "member":2, "role":"MASTER", "member_type":"user" } ]
[]
Response JSON Object: - permissions (array) – list of actual object permissions after operation.
Permission JSON Object: json fields
same as in
POST /api/v1/{object_kind}/{id}/permissions/
.
- object_kind – Kind of objects to perform operation. It can be
any present objects type in system:
-
PUT
/api/v1/{object_kind}/{id}/owner/
¶ Change owner of object.
Parameters: - object_kind – Kind of objects to perform operation. It can be
any present objects type in system:
hosts
,groups
,inventories
,projects
,templates
. - id – Id of object.
JSON Parameters: - id (number) – id of user.
PUT /api/v1/hosts/123/owner/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript 2
Results:
Owner changed
- object_kind – Kind of objects to perform operation. It can be
any present objects type in system:
-
GET
/api/v1/{object_kind}/{id}/owner/
¶ Get owner of object.
Parameters: - object_kind – Kind of objects to perform operation. It can be
any present objects type in system:
hosts
,groups
,inventories
,projects
,templates
. - id – Id of object.
Results:
2
Response JSON Object: - id (number) – id of owner.
- object_kind – Kind of objects to perform operation. It can be
any present objects type in system:
License (Polemarch+ only)¶
-
GET
/api/v1/license/
¶ Get details about your license.
Example request:
GET /api/v1/license/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ "expiry": null, "users": 5, "organization": "VST Consulting", "contacts": "sergey.k@vstconsulting.net", "hosts": null, "actual_hosts": 3, "actual_users": 2 }
Response JSON Object: - expiry (string) – date, when license will be (or was) expired. If null license is endless.
- users (number) – number of users available with this license. If null - unlimited.
- organization (string) – to whom this license is provided.
- contacts (string) – contatc information of license owner.
- hosts (number) – number of hosts available with this license. If null - unlimited.
- actual_hosts (number) – how many hosts (RANGE calculates appropriately) currently in system.
- actual_users (number) – how many users currently in system.