Rest API¶
Polemarch provides REST API for all it’s functionality accessible via web GUI, because our GUI also uses this API to work. Below there is information about every entity we have in Polemarch and methods applicable to it.
All urls methods are stated with /api/v1/
for first API version.
With other versions number will be changed. Current documentation is writen for
version 1. In this documentation all methods are 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 every kind result will look like:
-
GET
/api/v1/{something}/
¶ Gets 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 exist 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}/
¶ Gets 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", "notes":"some notes about this host", "type":"HOST", "vars":{ }, "owner": { "id": 1, "username": "admin", "is_active": true, "is_staff": true, "url": "http://localhost:8080/api/v1/users/1/" }, "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 on context of using this host during playbooks running).
- notes (string) – not required field for some user’s notes, for example, for what purpose this host was created or something like this.
- 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.
- owner (object) – owner of host. Supported fields
could be seen in
GET /api/v1/users/{id}/
. - url (string) – url to this specific host.
-
GET
/api/v1/hosts/
¶ Gets 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.
- type – type 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 are the same as in
GET /api/v1/hosts/{id}/
.
-
DELETE
/api/v1/hosts/{id}/
¶ Deletes host.
Parameters: - id – id of host.
-
POST
/api/v1/hosts/
¶ Creates host.
Request JSON Object: - name (string) – either human-readable name or hostname/IP or range of them (it is depends on context of using this host during playbooks running).
- notes (string) – not required field for some user’s notes, for example, for what purpose this host was created or something like this.
- 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", "notes":"", "type":"HOST", "vars":{ } }
Results:
{ "id":12, "name":"038108237241668497-0875926814493907", "notes":"", "type":"HOST", "vars":{ }, "owner": { "id": 1, "username": "admin", "is_active": true, "is_staff": true, "url": "http://localhost:8080/api/v1/users/1/" }, "url":"http://localhost:8080/api/v1/hosts/12/?format=json" }
Response JSON Object: response json fields are the same as in
GET /api/v1/hosts/{id}/
.
-
PATCH
/api/v1/hosts/{id}/
¶ Updates 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 are the 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" }
Results:
{ "id":12, "name":"038108237241668497-0875926814493907", "notes":"", "type":"HOST", "vars":{ }, "owner": { "id": 1, "username": "admin", "is_active": true, "is_staff": true, "url": "http://localhost:8080/api/v1/users/1/" }, "url":"http://localhost:8080/api/v1/hosts/12/?format=json" }
Response JSON Object: response json fields are the same as in
GET /api/v1/hosts/{id}/
.
Groups¶
-
GET
/api/v1/groups/{id}/
¶ Gets 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", "notes":"some notes about this group", "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, "owner": { "id": 1, "username": "admin", "is_active": true, "is_staff": true, "url": "http://localhost:8080/api/v1/users/1/" }, "url":"http://localhost:8080/api/v1/groups/1/" }
Response JSON Object: - id (number) – id of group.
- name (string) – name of group.
- notes (string) – not required field for some user’s notes, for example, for what purpose this group was created or something like this.
- 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.
- owner (object) – owner of group. Supported fields
could be seen in
GET /api/v1/users/{id}/
. - url (string) – url to this specific group.
-
GET
/api/v1/groups/
¶ Gets 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 are the same as in
GET /api/v1/groups/{id}/
.
-
DELETE
/api/v1/groups/{id}/
¶ Deletes group.
Parameters: - id – id of group.
-
POST
/api/v1/groups/
¶ Creates group.
Request JSON Object: - name (string) – name of new group.
- notes (string) – not required field for some user’s notes, for example, for what purpose this group was created or something like this.
- 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", "notes": "", "children":true, "vars":{ } }
Results:
{ "id":3, "name":"SomeGroup", "notes": "", "hosts":[ ], "groups":[ ], "vars":{ }, "children":true, "owner": { "id": 1, "username": "admin", "is_active": true, "is_staff": true, "url": "http://localhost:8080/api/v1/users/1/" }, "url":"http://localhost:8080/api/v1/groups/3/" }
Response JSON Object: response json fields are the same as in
GET /api/v1/groups/{id}/
.
-
PATCH
/api/v1/groups/{id}/
¶ Updates 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 are the 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" }
Results:
{ "id":3, "name":"SomeGroupChanged", "notes": "", "hosts":[ ], "groups":[ ], "vars":{ }, "children":true, "owner": { "id": 1, "username": "admin", "is_active": true, "is_staff": true, "url": "http://localhost:8080/api/v1/users/1/" }, "url":"http://localhost:8080/api/v1/groups/3/" }
Response JSON Object: response json fields are the same as in
GET /api/v1/groups/{id}/
.
-
POST
/api/v1/groups/{group_id}/hosts/
¶ Adds hosts to group. See Sublists for details.
Status Codes: - 409 Conflict – attempt to work with hosts list of children
group (
children=true
). This kind of groups is only for storing other groups within itself.
- 409 Conflict – attempt to work with hosts list of children
group (
-
PUT
/api/v1/groups/{group_id}/hosts/
¶ Replaces sublist of hosts with new one. See Sublists for details.
Status Codes: status codes are the same as in
POST /api/v1/groups/{group_id}/hosts/
.
-
DELETE
/api/v1/groups/{group_id}/hosts/
¶ Removes those hosts from group. See Sublists for details.
Status Codes: status codes are the same as in
POST /api/v1/groups/{group_id}/hosts/
.
-
POST
/api/v1/groups/{group_id}/groups/
¶ Adds subgroups to group. See Sublists for details.
Status Codes: - 409 Conflict – attempt to work with group list of not children group
(
children=false
). This kind of groups is only for storing hosts within itself.
- 409 Conflict – attempt to work with group list of not children group
(
-
PUT
/api/v1/groups/{group_id}/groups/
¶ Replaces sublist of subgroups with new one. See Sublists for details.
Status Codes: status codes are the same as in
POST /api/v1/groups/{group_id}/groups/
.
-
DELETE
/api/v1/groups/{group_id}/groups/
¶ Removes those subgroups from group. See Sublists for details.
Status Codes: status codes are the same as in
POST /api/v1/groups/{group_id}/groups/
.
Inventories¶
-
GET
/api/v1/inventories/{id}/
¶ Gets 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", "notes": "some notes about this inventory", "hosts":[ { "id": 7, "name": "test-host-0", "type": "HOST", "url": "http://localhost:8080/api/v1/hosts/7/" } ], "all_hosts": [ { "id": 7, "name": "test-host-0", "type": "HOST", "url": "http://localhost:8080/api/v1/hosts/7/" }, { "id": 8, "name": "test-host-from-test-group-1", "type": "HOST", "url": "http://localhost:8080/api/v1/hosts/8/" }, { "id": 9, "name": "test-host-from-test-group-2", "type": "HOST", "url": "http://localhost:8080/api/v1/hosts/9/" } ], "groups":[ { "id": 6, "name": "test-group", "children": false, "url": "http://localhost:8080/api/v1/groups/6/" } ], "vars":{ }, "owner": { "id": 1, "username": "admin", "is_active": true, "is_staff": true, "url": "http://localhost:8080/api/v1/users/1/" }, "url":"http://localhost:8080/api/v1/inventories/8/" }
Response JSON Object: - id (number) – id of inventory.
- name (string) – name of inventory.
- notes (string) – not required field for some user’s notes, for example, for what purpose this inventory was created or something like this.
- hosts (array) – list of hosts in inventory. See Hosts for fields explanation.
- all_hosts (array) – list of all hosts in inventory(includes also hosts from this inventory’s groups) . 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.
- owner (object) – owner of inventory. Supported fields
could be seen in
GET /api/v1/users/{id}/
. - url (string) – url to this specific inventory.
-
GET
/api/v1/inventories/
¶ Gets 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":2, "next":null, "previous":null, "results":[ { "id":8, "name":"Inventory1", "url":"http://localhost:8080/api/v1/inventories/8/" }, { "id":9, "name":"Inventory2", "url":"http://localhost:8080/api/v1/inventories/9/" } ] }
Response JSON Object: response json fields are the same as in
GET /api/v1/inventories/{id}/
.
-
DELETE
/api/v1/inventories/{id}/
¶ Deletes inventory.
Parameters: - id – id of inventory.
-
POST
/api/v1/inventories/
¶ Creates inventory.
Request JSON Object: - name (string) – name of new inventory.
- notes (string) – not required field for some user’s notes, for example, for what purpose this inventory was created or something like this.
- 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", "notes":"", "vars":{ } }
Results:
{ "id":9, "name":"Test servers", "notes":"", "hosts":[ ], "all_hosts":[ ] "groups":[ ], "vars":{ }, "owner": { "id": 1, "username": "admin", "is_active": true, "is_staff": true, "url": "http://localhost:8080/api/v1/users/1/" }, "url":"http://localhost:8080/api/v1/inventories/9/" }
Response JSON Object: response json fields are the same as in
GET /api/v1/inventories/{id}/
.
-
PATCH
/api/v1/inventories/{id}/
¶ Updates 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 are the 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":"New test servers" }
Results:
{ "id":9, "name":"New test servers", "notes":"", "hosts":[ ], "all_hosts":[ ] "groups":[ ], "vars":{ }, "owner": { "id": 1, "username": "admin", "is_active": true, "is_staff": true, "url": "http://localhost:8080/api/v1/users/1/" }, "url":"http://localhost:8080/api/v1/inventories/9/" }
Response JSON Object: response json fields are the same as in
GET /api/v1/inventories/{id}/
.
-
PUT
/api/v1/inventories/{inventory_id}/hosts/
¶ Replaces sublist of hosts with new one. See Sublists for details.
-
DELETE
/api/v1/inventories/{inventory_id}/hosts/
¶ Removes those hosts from inventory. See Sublists for details.
-
POST
/api/v1/inventories/{inventory_id}/groups/
¶ Adds groups to inventory. See Sublists for details.
Projects¶
-
GET
/api/v1/projects/{id}/
¶ Gets 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", "notes":"some notes about this project", "status":"WAIT_SYNC", "repository":"git@ex.us:dir/rep1.git", "hosts":[ ], "groups":[ ], "inventories":[ ], "vars":{ "repo_branch": "other", "repo_password":"forgetit", "repo_type":"GIT" }, "owner": { "id": 1, "username": "admin", "is_active": true, "is_staff": true, "url": "http://localhost:8080/api/v1/users/1/" }, "revision": "5471aeb916ee7f8754d55f159e532592b995b0ec", "branch": "master", "readme_content": null, "readme_ext": null, "url":"http://localhost:8080/api/v1/projects/7/" }
Response JSON Object: - id (number) – id of project.
- name (string) – name of project.
- notes (string) – not required field for some user’s notes, for example, for what purpose this project was created or something like this.
- repository (string) – URL of repository (repo-specific URL).
For
TAR
it is just HTTP-link to archive. - status (string) – current status of project. Possible values are:
NEW
- newly created project,WAIT_SYNC
- repository synchronization has been scheduled, but has not started to perform yet,SYNC
- synchronization is 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 variable
repo_type
always exists to store type of repository. Currently implemented types areGIT
- for Git repositories,TAR
- for uploading tar archive with project files andMANUAL
- for creating empty project or for uploading project files from server ‘manually’. ForGIT
projects such variables, asrepo_password
andrepo_branch
, are also available.repo_password
is needed to store password for repository(if it exists) andrepo_branch
means a branch of git project with which next synchronization will be done. - owner (object) – owner of project. Supported fields
could be seen in
GET /api/v1/users/{id}/
. - revision (string) –
GIT
revision - branch (string) – current branch of project, to which project has been synced last time.
- readme_content (string) – if project has “readme.md” or “readme.rst” file in it’s project directory, this field will contain content of readme file parsed to html
- readme_ext (string) – if project has “readme.md” or “readme.rst” file in it’s project directory, this field will contain extension of readme file
- url (string) – url to this specific inventory.
-
GET
/api/v1/projects/
¶ Gets 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}/
¶ Deletes project.
Parameters: - id – id of project.
-
POST
/api/v1/projects/
¶ Creates 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.
- notes (string) – not required field for some user’s notes, for example, for what purpose this project was created or something like this.
- vars (object) – dictionary of variables associated with this
object. See Variables for details. In this special case variable
repo_type
always exists to store type of repository. Currently implemented types areGIT
- for Git repositories,TAR
- for uploading tar archive with project files andMANUAL
- for creating empty project or for uploading project files from server ‘manually’. ForGIT
projects such variables, asrepo_password
andrepo_branch
, are also available.repo_password
is needed to store password for repository(if it exists) andrepo_branch
means a branch of git project with which next synchronization will be done. - 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", "notes":"", "repository":"http://example.com/project.tar", "vars":{ "repo_type":"TAR" } }
Results:
{ "id":9, "name":"project_owl", "notes":"", "status":"WAIT_SYNC", "repository":"http://example.com/project.tar", "hosts":[ ], "groups":[ ], "inventories":[ ], "vars":{ "repo_type":"TAR" }, "owner": { "id": 1, "username": "admin", "is_active": true, "is_staff": true, "url": "http://localhost:8080/api/v1/users/1/" }, "revision": "NO VCS", "branch": "NO VCS", "readme_content": null, "readme_ext": null, "url":"http://localhost:8080/api/v1/projects/9/" }
Response JSON Object: response json fields are the same as in
GET /api/v1/projects/{id}/
.
-
PATCH
/api/v1/projects/{id}/
¶ Updates project. Operation does not start synchronization again. If you want to synchronize, you should 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 are the 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_tar" }
Results:
{ "id":9, "name":"project_tar", "notes":"", "status":"WAIT_SYNC", "repository":"http://example.com/project.tar", "hosts":[ ], "groups":[ ], "inventories":[ ], "vars":{ "repo_type":"TAR" }, "owner": { "id": 1, "username": "admin", "is_active": true, "is_staff": true, "url": "http://localhost:8080/api/v1/users/1/" }, "revision": "NO VCS", "branch": "NO VCS", "readme_content": null, "readme_ext": null, "url":"http://localhost:8080/api/v1/projects/9/" }
Response JSON Object: response json fields are the same as in
GET /api/v1/projects/{id}/
.
-
PUT
/api/v1/projects/{project_id}/hosts/
¶ Replaces sublist of hosts with new one. See Sublists for details.
-
DELETE
/api/v1/projects/{project_id}/hosts/
¶ Removes those hosts from project. See Sublists for details.
-
PUT
/api/v1/projects/{project_id}/groups/
¶ Replaces sublist of groups with new one. See Sublists for details.
-
DELETE
/api/v1/projects/{project_id}/groups/
¶ Removes those groups from project. See Sublists for details.
-
POST
/api/v1/projects/{project_id}/inventories/
¶ Adds inventories to project. See Sublists for details.
-
PUT
/api/v1/projects/{project_id}/inventories/
¶ Replaces sublist of inventories with new one. See Sublists for details.
-
DELETE
/api/v1/projects/{project_id}/inventories/
¶ Removes those inventories from project. See Sublists for details.
-
GET
/api/v1/projects/supported-repos/
¶ Returns list of supported repository types.
Results:
[ "GIT", "MANUAL", "TAR" ]
-
POST
/api/v1/projects/{id}/sync/
¶ Starts synchronization. During this process project files are 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 rewriting of old files.Parameters: - id – id of project.
Results:
{ "detail":"Sync with git@ex.us:dir/rep1.git." }
-
POST
/api/v1/projects/{id}/execute-playbook/
¶ Executes 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 pass as additional command line arguments to
ansible-playbook
utility during execution, so you can use this feature for wide customization of ansible behaviour. For anykey:value
in command line there will be--key value
. If you want to post 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/
¶ Executes ansible module. It is just like running
ansible -m {something}
by hands. Instead of boring and time consuming dealing with playbooks you can do something quickly using ansible.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. It is just string raw
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 pass as additional command line arguments to
ansible-playbook
utility during execution, so you can use this feature to wide customization of ansible behaviour. For anykey:value
in command line there will be--key value
. If you want to post 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}/
¶ Gets 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/
¶ Gets list of 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":2, "next":null, "previous":null, "results":[ { "id":5, "name":"Ruin my environment", "playbook":"ruin_my_env.yml", "project":13 "url":"http://localhost:8080/api/v1/tasks/5/" }, { "id":6, "name":"Build my environment", "playbook":"build_my_env.yml", "project":13 "url":"http://localhost:8080/api/v1/tasks/6/" } ] }
Periodic tasks¶
-
GET
/api/v1/periodic-tasks/{id}/
¶ Gets 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, "name":"periodic-test", "notes":"some notes about this periodic task", "type":"CRONTAB", "schedule":"60* */2 sun,fri 1-15 *", "mode":"collect_data.yml", "kind":"PLAYBOOK", "project":7, "inventory":8, "save_result": true, "template": null, "template_opt": null, "enabled": true, "vars":{ }, "url":"http://127.0.0.1:8080/api/v1/periodic-tasks/10/?format=json" }
Response JSON Object: - id (number) – id of periodic task.
- name (string) – name of periodic task.
- notes (string) – not required field for some user’s notes, for example, for what purpose this periodic task was created or something like this.
- type (string) – type of periodic task. Either
INTERVAL
for tasks that run every N seconds orCRONTAB
for tasks, which run according to 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 expects string without year, because year format 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) –
PLAYBOOK
(if this task runs playbook),MODULE
(if this task runs module) orTEMPLATE
(if this task runs template). - project (number) – id of project, which this task belongs to.
- inventory (number) – id of inventory for which must execute_playbook playbook.
- save_result (boolean) – if
save_result
is true, the result will be saved. - template (number) – id of template (if kind is
PLAYBOOK
orMODULE
, this field will be equal to null). - template_opt (string) – name of template option (if kind is
PLAYBOOK
orMODULE
of if this periodic task executes template without option, this field will be equal to null). - enabled (boolean) – if
enabled
is true, the periodic task will be enabled. - vars (object) – those vars have special meaning. All those
parameters just pass as additional command line arguments to
ansible-playbook
utility during execution, so you can use this feature for wide customization of ansible behaviour. For anykey:value
in command line there will be--key value
. If you want to post only key without a value (--become
option for example), just passnull
as value. In all other cases 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/
¶ Gets 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, "name":"periodic-test", "type":"CRONTAB", "schedule":"60* */2 sun,fri 1-15 *", "mode":"collect_data.yml", "kind":"PLAYBOOK", "project":7, "inventory":8, "save_result": true, "template": null, "template_opt": null, "enabled": true, "url":"http://127.0.0.1:8080/api/v1/periodic-tasks/10/" }, { "id":11, "name":"periodic-test2", "type":"INTERVAL", "schedule":"20", "mode":"", "kind":"TEMPLATE", "project":7, "inventory":8, "save_result": true, "template": 1, "template_opt": "some-vars", "enabled": true, "url":"http://127.0.0.1:8080/api/v1/periodic-tasks/11/" } ] }
Response JSON Object: response json fields are the same as in
GET /api/v1/periodic-tasks/{id}/
.
-
DELETE
/api/v1/periodic-tasks/{id}/
¶ Deletes periodic task.
Parameters: - id – id of periodic task.
-
POST
/api/v1/periodic-tasks/
¶ Creates periodic task
Example request:
POST /api/v1/periodic-tasks/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript { "name":"new-periodic-test", "notes":"", "type": "INTERVAL", "schedule": "25", "mode": "touch_the_clouds.yml", "kind": "PLAYBOOK", "project": 7, "inventory": 8, "save_result": true, "template": null, "template_opt": null, "enabled": true, "vars":{ }, }
Results:
{ "id": 14, "name":"new-periodic-test", "notes":"", "type": "INTERVAL", "schedule": "25", "mode": "touch_the_clouds.yml", "kind": "PLAYBOOK", "project": 7, "inventory": 8, "save_result": true, "template": null, "template_opt": null, "enabled": true, "vars":{ }, "url": "http://127.0.0.1:8080/api/v1/periodic-tasks/14/?format=api" }
Response JSON Object: response json fields are the same as in
GET /api/v1/periodic-tasks/{id}/
.
-
PATCH
/api/v1/periodic-tasks/{id}/
¶ Updates 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 are the 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": "60" }
Results:
{ "id": 14, "name":"new-periodic-test", "notes":"", "type": "INTERVAL", "schedule": "60", "mode": "touch_the_clouds.yml", "kind": "PLAYBOOK", "project": 7, "inventory": 8, "save_result": true, "template": null, "template_opt": null, "enabled": true, "vars":{ }, "url": "http://127.0.0.1:8080/api/v1/periodic-tasks/14/?format=api" }
Response JSON Object: response json fields are the same as in
GET /api/v1/periodic-tasks/{id}/
.
-
POST
/api/v1/periodic-tasks/{id}/execute/
¶ Executes periodic task.
Parameters: - id – id of periodic task.
Example request:
POST /api/v1/periodic-tasks/14/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript { "name":"new-periodic-test", "notes":"", "type": "INTERVAL", "schedule": "60", "mode": "touch_the_clouds.yml", "kind": "PLAYBOOK", "project": 7, "inventory": 8, "save_result": true, "template": null, "template_opt": null, "enabled": true, "vars":{ } }
Results:
{ "history_id": 158, "detail": "Started at inventory 8." }
Request JSON Object: request json fields are the same as in
GET /api/v1/periodic-tasks/{id}/
.
Templates¶
-
GET
/api/v1/templates/{id}/
¶ Gets 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", "notes": "some notes about this template", "kind": "Task", "owner": { "id": 1, "username": "admin", "is_active": true, "is_staff": true, "url": "http://localhost:8080/api/v1/users/1/" }, "data": { "project": 1, "inventory": 10, "playbook": "test.yml", "vars": { "connection": "paramiko" } }, "options": { "only-local": { "playbook": "other.yml", }, "only-server": { "vars": { "forks": "10", "limit": "Test-server" } } }, "options_list": [ "only-local", "only-server" ] }
Response JSON Object: - id (number) – id of template.
- name (string) – name of template.
- notes (string) – not required field for some user’s notes, for example, for what purpose this template was created or something like this.
- kind (string) – kind of template. Supported kinds
could be seen in
GET /api/v1/templates/supported-kinds/
. - owner (object) – owner of template. Supported fields
could be seen in
GET /api/v1/users/{id}/
. - data (string) – JSON structure of template. Supported
fields could see in
GET /api/v1/templates/supported-kinds/
. - options (object) – tepmlate options, which can update some template’s settings before new execution.
- options_list (array) – list of options’ names for this template.
-
GET
/api/v1/templates/
¶ Gets 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": 2, "next": null, "previous": null, "results": [ { "id": 1, "name": "test_tmplt", "kind": "Task", "options_list": [ "only-local", "only-server" ] }, { "id": 2, "name": "test_tmplm", "kind": "Module", "options_list": [ ] } ] }
Response JSON Object: response json fields are the same as in
GET /api/v1/templates/{id}/
.
-
DELETE
/api/v1/templates/{id}/
¶ Deletes periodic task.
Parameters: - id – id of periodic task.
-
POST
/api/v1/templates/
¶ Creates template
Request JSON Object: - name (string) – template name.
- notes (string) – not required field for some user’s notes, for example, for what purpose this template was created or something like this.
- kind (string) – kind of template. Supported kinds
could be seen in
GET /api/v1/templates/supported-kinds/
. - data (string) – JSON structure of template. Supported
fields could see in
GET /api/v1/templates/supported-kinds/
. - options (string) – template options, which can update some template’s settings before new execution.
Example request:
POST /api/v1/templates/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript { "name": "test", "notes":"", "kind": "Task", "data": { "project": 1, "inventory": 10, "playbook": "test.yml", "vars": { "connection": "paramiko" } }, "options": { "playbook": "other.yml" } }
Results:
{ "id": 3, "name": "test", "notes":"", "kind": "Task", "data": { "project": 1, "inventory": 10, "playbook": "test.yml", "vars": { "connection": "paramiko" } }, "options": { "playbook": "other.yml" } }
Response JSON Object: response json fields are the same as in
GET /api/v1/templates/{id}/
.
-
PATCH
/api/v1/templates/{id}/
¶ Updates template. If you want to update data, you 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 are the 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": 3, "name": "test_new_name", "notes":"", "kind": "Task", "data": { "project": 1, "inventory": 10, "playbook": "test.yml", "vars": { "connection": "paramiko" } }, "options": { "playbook": "other.yml" } }
Response JSON Object: response json fields are the same as in
GET /api/v1/templates/{id}/
.
-
POST
/api/v1/templates/{id}/execute/
¶ Executes template.
Parameters: - id – id of template.
Example request:
POST /api/v1/templates/3/execute/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript { "name": "test_new_name", "kind": "Task", "data": { "project": 1, "inventory": 10, "playbook": "test.yml", "vars": { "connection": "paramiko" } }, "options": { "option": "playbook" } }
Results:
{ "history_id": 205, "detail": "Started at inventory 10." }
Response JSON Object: response json fields are the same as in
GET /api/v1/templates/{id}/
.
-
GET
/api/v1/templates/supported-kinds/
¶ Gets list of supported kinds. Pagination is used for this list.
Example request:
GET /api/v1/history/supported-kinds/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ "Group": [ "name", "vars", "children" ], "Host": [ "name", "vars" ], "Task": [ "playbook", "vars", "inventory", "project" ], "PeriodicTask": [ "type", "name", "schedule", "inventory", "kind", "mode", "project", "vars" ], "Module": [ "inventory", "module", "group", "args", "vars", "project" ] }
History records¶
-
GET
/api/v1/history/{id}/
¶ Gets 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:16.922777Z", "execution_time": 5, "inventory": 4, "raw_inventory":"inventory", "raw_args": "ansible-playbook main.yml -i /tmp/tmpvMIwMg -v", "raw_stdout":"http://localhost:8080/api/v1/history/1/raw/", "initiator": 1, "initiator_type": "project", "executor": 1, "execute_args": { "diff": "", "become": "" }, "revision": "NO VCS", "options": {}, "url": "http://localhost:8080/api/v1/history/1/" }
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) – kind of task:
PLAYBOOK
orMODULE
. - status (string) – either
DELAY
,OK
,INTERRUPTED
,RUN
,OFFLINE
orERROR
, which indicates different results of execution (scheduled for run, successful run, 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)
- execution_time (number) – time taken to perform task execution (in seconds).
- inventory (number) – id of inventory.
- raw_inventory (string) – ansible inventory, which was used for execution. It was generated from Polemarch’s Inventories
- raw_args (string) – ansible command line during execution.
- raw_stdout (string) – what Ansible has written 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.
- executor (number) – id of user, who executed task.
- execute_args (object) – arguments, which were used during execution.
- revision (string) – project revision.
- options (object) – some additional options, which were used during this task execution. For example, if you execute some template with option, name of this option will be saved to this object.
- url (string) – url to this specific history record.
-
POST
/api/v1/history/{id}/cancel/
¶ Cancels 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/
¶ Gets full output of executed task.
Parameters: - id – id of history record.
Query Parameters: - color – Default is
no
. If it isyes
, 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/
¶ Gets 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" } ] }
-
DELETE
/api/v1/history/{id}/clear/
¶ Deletes full output of executed task.
Parameters: - id – id of history record.
Example request:
DELETE /api/v1/history/1/clear/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ "detail": "Output trancated.\n" }
Response JSON Object: - detail (string) – new output for history record’s stdout.
-
GET
/api/v1/history/
¶ Gets 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. - initiator – filter by
initiator
. - initiator_type – filter by
initiator_type
.
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", "inventory": 6, "status": "OK", "start_time": "2017-07-24T06:39:52.052504Z", "stop_time": "2017-07-24T06:41:06.521813Z", "initiator": 1, "initiator_type": "project", "executor": 1, "options": {}, "url": "http://localhost:8000/api/v1/history/121/" }, { "id": 118, "project": 4, "mode": "ping", "kind": "MODULE", "inventory": 7, "status": "OK", "start_time": "2017-07-24T06:27:40.481588Z", "stop_time": "2017-07-24T06:27:42.499873Z", "initiator": 2, "initiator_type": "template", "executor": 1, "options": { "template_option": "some-vars" }, "url": "http://localhost:8000/api/v1/history/118/" } ] }
Response JSON Object: response json fields are the same as in
GET /api/v1/history/{id}/
.
-
DELETE
/api/v1/history/{id}/
¶ Deletes history record.
Parameters: - id – id of record.
-
GET
/api/v1/history/{id}/facts/
¶ Gets 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 are still not ready, because module is currently running or only scheduled for run.
Ansible¶
-
GET
/api/v1/ansible/
¶ Gets 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/
¶ Gets 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 (for exapmle, periodic_playbook or periodic_module).
Example request:
GET /api/v1/ansible/cli_reference/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ "periodic_playbook": { "flush-cache": { "shortopts": [], "type": "boolean", "help": "clear the fact cache" }, "extra-vars": { "type": "text", "help": "set additional variables as key=value or YAML/JSON" }, // there is much more arguments to type it here // ... }, "playbook": { "flush-cache": { "shortopts": [], "type": "boolean", "help": "clear the fact cache" }, "extra-vars": { "type": "text", "help": "set additional variables as key=value or YAML/JSON" }, // there is much more arguments to type it here // ... }, "module": { "extra-vars": { "type": "text", "help": "set additional variables as key=value or YAML/JSON" }, "help": { "shortopts": [ "h" ], "type": "boolean", "help": "show this help message and exit" }, // there is much more arguments to type it here // ... }, "periodic_module": { "extra-vars": { "type": "text", "help": "set additional variables as key=value or YAML/JSON" }, "help": { "shortopts": [ "h" ], "type": "boolean", "help": "show this help message and exit" }, // there is much more arguments to type it here // ... } }
-
GET
/api/v1/ansible/modules/
¶ Gets 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:
[ "source_control.github_hooks", "source_control.git_config", "source_control.github_issue", "source_control.git", "source_control.github_deploy_key", "source_control.gitlab_project", "source_control.github_release", "source_control.gitlab_group", "source_control.github_key", "source_control.gitlab_user" ]
Statistic list¶
Sometimes application needs to provide user with some statistic information like amount of different objects or frequency of executing some tasks and so on. For such kind of work we use our API’s statistic list, which can provide user with information about amount of templates, users, teams, hosts, groups, inventories, projects in system in current moment and to tell him how many tasks of each status have been executed during last days, months and years.
-
GET
/api/v1/stats/
¶ Gets statistic list.
Query Parameters: - last – filter to search statistic information for certain amount of past days (by default the last is 14, this filter is measured in days).
Example request:
GET /api/v1/stats/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ "templates": 7, "users": 1, "teams": 0, "hosts": 10, "groups": 5, "inventories": 4, "projects": 3, "jobs": { "month": [ { "status": "ERROR", "sum": 6, "all": 47, "month": "2018-03-01T00:00:00Z" }, { "status": "OFFLINE", "sum": 5, "all": 47, "month": "2018-03-01T00:00:00Z" }, { "status": "OK", "sum": 36, "all": 47, "month": "2018-03-01T00:00:00Z" } ], "day": [ { "status": "ERROR", "sum": 3, "day": "2018-03-05T00:00:00Z", "all": 10 }, { "status": "OK", "sum": 7, "day": "2018-03-05T00:00:00Z", "all": 10 }, { "status": "ERROR", "sum": 2, "day": "2018-03-06T00:00:00Z", "all": 30 }, { "status": "OFFLINE", "sum": 5, "day": "2018-03-06T00:00:00Z", "all": 30 }, { "status": "OK", "sum": 23, "day": "2018-03-06T00:00:00Z", "all": 30 }, { "status": "ERROR", "sum": 1, "day": "2018-03-07T00:00:00Z", "all": 7 }, { "status": "OK", "sum": 6, "day": "2018-03-07T00:00:00Z", "all": 7 } ], "year": [ { "status": "ERROR", "sum": 6, "all": 47, "year": "2018-01-01T00:00:00Z" }, { "status": "OFFLINE", "sum": 5, "all": 47, "year": "2018-01-01T00:00:00Z" }, { "status": "OK", "sum": 36, "all": 47, "year": "2018-01-01T00:00:00Z" } ] } }
Response JSON Object: - templates (number) – amount of templates in system in current moment.
- users (number) – amount of users in system in current moment.
- teams (number) – amount of teams in system in current moment. (Polemarch+ only)
- hosts (number) – amount of hosts in system in current moment.
- groups (number) – amount of groups in system in current moment.
- inventories (number) – amount of inventories in system in current moment.
- projects (number) – amount of projects in system in current moment.
- jobs (object) – amount of executed tasks during last days, months, years.
Variables¶
Hosts, groups, inventories and projects in Polemarch may have variables associated with them. Usually (with one exception - variables for additional repository data in Projects) those variables pass to Ansible to customize his behaviour or playbook logic in certain way. In all these kinds of objects variables work in the same way, so there is an 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 by POST
request and can be completely owerwritted by PATCH
request.
It can be represented in such more formal way:
-
GET
/api/v1/{object_kind}/{object_id}
¶ Gets 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}
¶ Updates object.
Parameters: - id – id of object.
Request JSON Object: - vars (object) – new dictionary of variables for object. It 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_string2", "integer_variable2": 15, "float_variable3": 0.5 } }
Results:
{ // object-special data goes here "vars":{ "string_variable1": "some_string2", "integer_variable2": 15, "float_variable3": 0.5 }, }
Also for all previously enumerated kinds of objects (which support variables) there is variable filtering, which is available in get requests:
-
GET
/api/v1/{object_kind}/
¶ Gets 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
Results:
{ "count": 1, "next": null, "previous": null, "results": [ { "id": 12, "name": "git", "children": true, "url": "http://localhost:8080/api/v1/groups/12/" } ] }
- variables – filter objects by variables and their values. Variables
specified as list using
Sublists¶
Many of object 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 are based on the same logic, we have documented here general principles of this logic in order not to duplicate this information for every single method.
There is 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 a plenty of urls and for every url POST
, PUT
and
DELETE
methods are presented. Every method takes list of IDs from json request
body, but perform different operations with those IDs. PUT
method completely
rewrites sublist with new list. POST
method just appends 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": []
}
Here not_found
is a counter for items, which can’t be processed for some
reason. operated
is a counter for items processed successfully. total
is a number of
elements which were in initial request. If some items are not operated successfully, they will be added to
failed_list
. Otherwise failed_list
will be empty.
List of IDs means objects’ IDs 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 this list is not exist, method will still return 200 OK
, but result’s stats will
reflect the fact, that one of the ids can’t be processed successfully.
To clarify information above there is detailed explanation (with request and response examples) of those methods’ logic:
-
ANY
/api/v1/{object_kind}/{object_id}/{sublist_kind}/
¶ Operates with sublist of objects for some concrete object.
POST
- appends new objects to already existent sublist.DELETE
- removes those objects from existent sublist.PUT
- rewrites 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/from 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) – number of items processed with error (not exists or no access).
- operated (number) – number of items processed successfully.
- total (number) – number of all sent ids.
Hooks¶
Polemarch has his own system of hooks. Polemarch hooks are synchronous and you can appoint them on different events like “after end task”, “before start task” and so on.
More information about hooks types and events ou can find here GET /api/v1/hooks/types/
.
WARNING: You should be accurate with hooks appointment, because the more hooks you have, the more time they need for execution and, finally, the more time Ansible needs for task execution.
-
GET
/api/v1/hooks/
¶ Gets hooks list.
Parameters: - id – filter by id of hook.
- id__not – filter by id of hook (except this id).
- name – filter by name of hook.
- type – filter by type of hook.
Example request:
GET /api/v1/hooks/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ { "id": 1, "name": "test hook on user add", "type": "HTTP", "when": "on_user_add", "enable": true, "recipients": "http://localhost:8000/hook_trigger" }, { "id": 2, "name": "all hooks", "type": "HTTP", "when": null, "enable": false, "recipients": "http://localhost:8000/hook_trigger_another" }, { "id": 3, "name": "Script hooks", "type": "SCRIPT", "when": null, "enable": true, "recipients": "test.sh" } }
Response JSON Object: - id (number) – id of hook.
- name (string) – name of hook.
- type (string) – type of hook. For more details look
GET /api/v1/hooks/types/
. - when (string) – type of event on which hook will be executed. If
when
isnull
, this hook will be executed for every type of event. For more details lookGET /api/v1/hooks/types/
. - enable (boolean) – if this field is true, hook will be executed.
- recipients (string) – recipients of hook.
-
GET
/api/v1/hooks/{id}/
¶ Gets details about one hook.
Parameters: - id – id of hook.
Example request:
GET /api/v1/hooks/1/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ "id": 1, "name": "test hook on user add", "type": "HTTP", "when": "on_user_add", "enable": true, "recipients": "http://localhost:8000/hook_trigger" }
Response JSON Object: response json fields are the same as in
GET /api/v1/hooks/
.
-
POST
/api/v1/hooks/
¶ Creates new hook.
Example request:
POST /api/v1/hooks/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript { "name": "new hook", "type": "SCRIPT", "when": "on_execution", "enable": true, "recipients": "new-test.sh" }
Results:
{ "id": 4, "name": "new hook", "type": "SCRIPT", "when": "on_execution", "enable": true, "recipients": "new-test.sh" }
Response JSON Object: response json fields are the same as in
GET /api/v1/hooks/
.If
type
isSCRIPT
and there is no'new-test.sh'
in hooks dir,POST
request will return 400 Bad Request.
-
GET
/api/v1/hooks/types/
¶ Returns list of supported hook’s types and events.
Example request:
GET /api/v1/hooks/types/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
{ "when": { "after_execution": "After end task", "on_user_add": "When new user register", "on_user_del": "When user was removed", "on_execution": "Before start task", "on_object_add": "When new Polemarch object was added", "on_object_upd": "When Polemarch object was updated", "on_object_del": "When Polemarch object was removed", "on_user_upd": "When user update data" }, "types": [ "HTTP", "SCRIPT" ] }
Response JSON Object: - when (string) – type of event on which hook will be executed.
- types (string) – type of hook. If
type
isHTTP
, hook will send JSON byPOST
request to url, which is inrecipients
field of hook. Iftype
isSCRIPT
, hook will send a temporery file with JSON to script, name of which is inrecipients
field of hook.
Token¶
-
POST
/api/v1/token/
¶ Creates new token.
Example request:
POST /api/v1/token/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript { "username": "test-user", "password": "password" }
Results:
{ "token": "f9e983ef5f67725b60f5a4a1aa0f32912ebe05fb" }
-
DELETE
/api/v1/token/
¶ Deletes token.
Example request:
DELETE /api/v1/token/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript { "token": "f9e983ef5f67725b60f5a4a1aa0f32912ebe05fb" }
Results:
{ }
Users¶
-
GET
/api/v1/users/{id}/
¶ Gets 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", "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) – if it is
true
, account is enabled. - is_staff (boolean) – if it is
true
, this user is superuser. Superuser has 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/
¶ Gets 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, "is_staff": true, "url":"http://127.0.0.1:8080/api/v1/users/1/" }, { "id":3, "username":"petya", "is_active":true, "is_staff": true, "url":"http://127.0.0.1:8080/api/v1/users/3/" } ] }
Response JSON Object: response json fields are the same as in
GET /api/v1/users/{id}/
.
-
DELETE
/api/v1/users/{id}/
¶ Deletes user.
Parameters: - id – id of user.
-
POST
/api/v1/users/
¶ Creates user.
Request JSON Object: - username (string) – login.
- password (string) – password.
- is_active (boolean) – if it is
true
, account is enabled. - is_staff (boolean) – if it is
true
, this user is 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", "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 are the same as in
GET /api/v1/users/{id}/
.
-
PATCH
/api/v1/users/{id}/
¶ Updates user. All parameters except id are optional, so you can specify only needed to update. Only name, for example.
Parameters: - id – id of user.
Request JSON Object: request json fields are the 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 { "username":"petrusha" }
Results:
{ "id":3, "username":"petrusha", "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 are the same as in
GET /api/v1/users/{id}/
.
-
POST
/api/v1/users/{id}/settings/
¶ Creates user’s view settings of Dashboard’s widgets.
Parameters: - id – id of user.
Example request:
POST /api/v1/users/{id}/settings/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript { "chartLineSettings": { "ok": { "active": true }, "all_tasks": { "active": true }, "interrupted": { "active": true }, "delay": { "active": true }, "error": { "active": true }, "offline": { "active": true } }, "widgetSettings": { "pmwTasksTemplatesWidget": { "active": false, "sortNum": 8, "collapse": false }, "pmwUsersCounter": { "active": true, "sortNum": 5, "collapse": false }, "pmwProjectsCounter": { "active": true, "sortNum": 3, "collapse": false }, "pmwHostsCounter": { "active": true, "sortNum": 0, "collapse": false }, "pmwInventoriesCounter": { "active": true, "sortNum": 2, "collapse": false }, "pmwGroupsCounter": { "active": true, "sortNum": 1, "collapse": false }, "pmwChartWidget": { "active": true, "sortNum": 6, "collapse": false }, "pmwModulesTemplatesWidget": { "active": false, "sortNum": 9, "collapse": false }, "pmwTemplatesCounter": { "active": true, "sortNum": 4, "collapse": false }, "pmwAnsibleModuleWidget": { "active": true, "sortNum": 7, "collapse": true } } }
Results:
{ "chartLineSettings": { "ok": { "active": true }, "all_tasks": { "active": true }, "interrupted": { "active": true }, "delay": { "active": true }, "error": { "active": true }, "offline": { "active": true } }, "widgetSettings": { "pmwTasksTemplatesWidget": { "active": false, "sortNum": 8, "collapse": false }, "pmwUsersCounter": { "active": true, "sortNum": 5, "collapse": false }, "pmwProjectsCounter": { "active": true, "sortNum": 3, "collapse": false }, "pmwHostsCounter": { "active": true, "sortNum": 0, "collapse": false }, "pmwInventoriesCounter": { "active": true, "sortNum": 2, "collapse": false }, "pmwGroupsCounter": { "active": true, "sortNum": 1, "collapse": false }, "pmwChartWidget": { "active": true, "sortNum": 6, "collapse": false }, "pmwModulesTemplatesWidget": { "active": false, "sortNum": 9, "collapse": false }, "pmwTemplatesCounter": { "active": true, "sortNum": 4, "collapse": false }, "pmwAnsibleModuleWidget": { "active": true, "sortNum": 7, "collapse": true } } }
Response JSON Object: - chartLineSettings (object) – object with Dashboard chart line settings.
- active (boolean) – one of Dashboard chart line settings, if
active
istrue
, this line will be visible on Dashboard. - widgetSettings (object) – object with Dashboard widgets settings.
- pmw{widget_Name} (string) – widget name.
- active – one of widget’s settings, if
active
istrue
, this widget will be visible on Dashboard. - sortNum (number) – one of widget’s settings, it means order number of widget on Dashboard.
- collapse (boolean) – one of widget’s settings, if
collapse
istrue
, this widget will be collapsed on Dashboard.
-
GET
/api/v1/users/{id}/settings/
¶ Gets user’s view settings of Dashboard’s widgets.
Parameters: - id – id of user.
Example request:
GET /api/v1/users/{id}/settings/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript { }
Results:
{ "chartLineSettings": { "ok": { "active": true }, "all_tasks": { "active": true }, "interrupted": { "active": true }, "delay": { "active": true }, "error": { "active": true }, "offline": { "active": true } }, "widgetSettings": { "pmwTasksTemplatesWidget": { "active": false, "sortNum": 8, "collapse": false }, "pmwUsersCounter": { "active": true, "sortNum": 5, "collapse": false }, "pmwProjectsCounter": { "active": true, "sortNum": 3, "collapse": false }, "pmwHostsCounter": { "active": true, "sortNum": 0, "collapse": false }, "pmwInventoriesCounter": { "active": true, "sortNum": 2, "collapse": false }, "pmwGroupsCounter": { "active": true, "sortNum": 1, "collapse": false }, "pmwChartWidget": { "active": true, "sortNum": 6, "collapse": false }, "pmwModulesTemplatesWidget": { "active": false, "sortNum": 9, "collapse": false }, "pmwTemplatesCounter": { "active": true, "sortNum": 4, "collapse": false }, "pmwAnsibleModuleWidget": { "active": true, "sortNum": 7, "collapse": true } } }
Response JSON Object: - chartLineSettings (object) – object with Dashboard chart line settings.
- active (boolean) – one of Dashboard chart line settings, if
active
istrue
, this line will be visible on Dashboard. - widgetSettings (object) – object with Dashboard widgets settings.
- pmw{widget_Name} (string) – widget name.
- active – one of widget’s settings, if
active
istrue
, this widget will be visible on Dashboard. - sortNum (number) – one of widget’s settings, it means order number of widget on Dashboard.
- collapse (boolean) – one of widget’s settings, if
collapse
istrue
, this widget will be collapsed on Dashboard.
-
DELETE
/api/v1/users/{id}/settings/
¶ Deletes user’s view settings of Dashboard’s widgets.
Parameters: - id – id of user.
Teams (Polemarch+ only)¶
Team is a group of users to which you can collectively assign rights to objects in ACL system.
-
GET
/api/v1/teams/{id}/
¶ Gets 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", "notes": "some notes about this team", "users": [ { "id": 1, "username": "admin", "is_active": true, "is_staff": true, "url": "http://localhost:8000/api/v1/users/1/" }, { "id": 2, "username": "test-user", "is_active": true, "is_staff": false, "url": "http://localhost:8081/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/1/" }
Response JSON Object: - id (number) – id of team.
- name (string) – name of team.
- notes (string) – not required field for some user’s notes, for example, for what purpose this team was created or something like this.
- users (array) – array of users in team. See Users for fields explanation.
- users_list (array) – ids of users in team.
- owner (object) – owner of team. See Users for fields explanation.
- url (string) – url to this specific team.
-
GET
/api/v1/teams/
¶ Gets 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 are the same as in
GET /api/v1/teams/{id}/
.
-
DELETE
/api/v1/teams/{id}/
¶ Deletes team.
Parameters: - id – id of team.
-
POST
/api/v1/teams/
¶ Creates team.
Request JSON Object: - name (string) – name of new team.
- notes (string) – not required field for some user’s notes, for example, for what purpose this team was created or something like this.
Example request:
POST /api/v1/teams/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript { "name":"another_team", "notes":"" }
Results:
{ "id": 2, "name": "another_team", "notes":"", "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 are the same as in
GET /api/v1/teams/{id}/
.
-
PATCH
/api/v1/groups/{id}/
¶ Updates 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, 3] }
Results:
{ "id": 2, "name": "another_team", "notes":"", "users": [ { "id": 1, "username": "admin", "is_active": true, "is_staff": true, "url": "http://localhost:8000/api/v1/users/1/" }, { "id": 3, "username": "max", "is_active": true, "is_staff": true, "url": "http://localhost:8000/api/v1/users/3/" } ], "users_list": [ 1, 3 ], "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 are the same as in
GET /api/v1/teams/{id}/
.
ACL system (Polemarch+ only)¶
Because Polemarch supports multiple users it has access rights for every kind of objects. Most kinds of objects (if to be precise: Hosts, Groups, Inventories, Projects, Templates, Teams (Polemarch+ only) ) 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 have not their own permissions, but permissions of parent objects are 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 - is the same as above + right to edit.
- MASTER - is the same as above + can work with permissions list for this object (add/delete other users and teams).
- OWNER - is the same as above + ability to change owner.
Warning: if you grant somebody EXECUTOR permission to object, he will also automatically get EXECUTOR rights to all other objects, which are required to use this one. Example: if you give User1 EDITOR right to Inventory1, he will also get EXECUTOR to all hosts and groups, which are currently listed in Inventory1.
Also there are two types of users: regular and superuser. Regular users have access only to objects, where they are listed in permissions. Superusers have access to all objects in system. See Users for detailed information about user management API.
Polemarch+ has such methods to control ownership and permissions information:
-
GET
/api/v1/{object_kind}/{id}/permissions/
¶ Gets permissions to object.
Parameters: - object_kind – kind of objects to perform operation. It can be one of
any presented object type in system:
hosts
,groups
,inventories
,projects
,templates
,teams
. - id – Id of object.
Example request:
POST /api/v1/teams/1/permissions/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
[ { "member":2, "role":"EXECUTOR", "member_type":"user" } ]
Response JSON Object: - permissions (array) – list of permissions. Permission JSON Object: json fields are the
same as in
POST /api/v1/{object_kind}/{id}/permissions/
.
- object_kind – kind of objects to perform operation. It can be one of
any presented object type in system:
-
POST
/api/v1/{object_kind}/{id}/permissions/
¶ Adds those permissions to object.
Parameters: - object_kind – kind of objects to perform operation. It can be one of
any presented object type in system:
hosts
,groups
,inventories
,projects
,templates
,teams
. - 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/teams/1/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 the 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 one of
any presented object type in system:
-
PUT
/api/v1/{object_kind}/{id}/permissions/
¶ Replaces permissions to object with provided.
Parameters: - object_kind – kind of objects to perform operation. It can be one of
any presented object type in system:
hosts
,groups
,inventories
,projects
,templates
,teams
. - id – Id of object.
Request JSON Object: - permissions (array) – new permissions list. Permission JSON Object: json fields are the
same as in
POST /api/v1/{object_kind}/{id}/permissions/
.
PUT /api/v1/teams/1/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 are the
same as in
POST /api/v1/{object_kind}/{id}/permissions/
.
- object_kind – kind of objects to perform operation. It can be one of
any presented object type in system:
-
DELETE
/api/v1/{object_kind}/{id}/permissions/
¶ Removes access to object for users, which are listed in json array in request’s body.
Parameters: - object_kind – kind of objects to perform operation. It can be one of
any presented object type in system:
hosts
,groups
,inventories
,projects
,templates
,teams
. - id – id of object.
Request JSON Object: - permissions (array) – which permissions should be removed. You can use PUT with
empty list if you want to remove all permissions. Permission JSON Object: json fields are the
same as in
POST /api/v1/{object_kind}/{id}/permissions/
.
Example request:
DELETE /api/v1/teams/1/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:
[]
Response JSON Object: - permissions (array) – list of actual object permissions after operation.
Permission JSON Object: json fields are the
same as in
POST /api/v1/{object_kind}/{id}/permissions/
.
- object_kind – kind of objects to perform operation. It can be one of
any presented object type in system:
-
PUT
/api/v1/{object_kind}/{id}/owner/
¶ Changes owner of object.
Parameters: - object_kind – kind of objects to perform operation. It can be one of
any presented object type in system:
hosts
,groups
,inventories
,projects
,templates
,teams
. - id – Id of object.
JSON Parameters: - id (number) – id of user.
Example request:
PUT /api/v1/teams/1/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 one of
any presented object type in system:
-
GET
/api/v1/{object_kind}/{id}/owner/
¶ Gets owner of object.
Parameters: - object_kind – kind of objects to perform operation. It can be one of
any presented object type in system:
hosts
,groups
,inventories
,projects
,templates
,teams
. - id – Id of object.
Example request:
GET /api/v1/teams/1/permissions/owner/ HTTP/1.1 Host: example.com Accept: application/json, text/javascript
Results:
2
Response JSON Object: - id (number) – id of owner.
- object_kind – kind of objects to perform operation. It can be one of
any presented object type in system:
License (Polemarch+ only)¶
-
GET
/api/v1/license/
¶ Gets 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 are available with this license. If null - unlimited.
- organization (string) – to whom this license is provided.
- contacts (string) – license owner’s contact information .
- hosts (number) – number of hosts which are available with this license. If null - unlimited.
- actual_hosts (number) – how many hosts are (RANGE calculates appropriately) currently in system.
- actual_users (number) – how many users are currently in system.