Method Path Description
GET /v1/roles Get all roles
GET /v1/roles/{uid} Get a single role
PUT /v1/roles/{uid} Update an existing role
POST /v1/roles Create a new role
DELETE /v1/roles/{uid} Delete a role

Get all roles

GET /v1/roles

Get all roles' details.

Permissions

Permission name Roles
view_all_roles_info admin
cluster_member
cluster_viewer
db_member
db_viewer

Request

Example HTTP request

GET /roles

Headers

Key Value Description
Host cnm.cluster.fqdn Domain name
Accept application/json Accepted media type

Response

Returns a JSON array of role objects.

Example JSON body

[
    {
        "uid": 1,
        "name": "Admin",
        "management": "admin"
    },
    {
        "uid": 2,
        "name": "Cluster Member",
        "management": "cluster_member"
    },
    {
        "uid": 3,
        "name": "Cluster Viewer",
        "management": "cluster_viewer"
    },
    {
        "uid": 4,
        "name": "DB Member",
        "management": "db_member"
    },
    {
        "uid": 5,
        "name": "DB Viewer",
        "management": "db_viewer"
    },
    {
        "uid": 6,
        "name": "None",
        "management": "none"
    },
    {
        "uid": 17,
        "name": "DBA",
        "management": "admin"
    }
]

Status codes

Code Description
200 OK No error
501 Not Implemented Cluster doesn’t support roles yet.

Get role

GET /v1/roles/{int: uid}

Get the details of a single role.

Permissions

Permission name Roles
view_role_info admin
cluster_member
cluster_viewer
db_member
db_viewer

Request

Example HTTP request

GET /roles/1

Headers

Key Value Description
Host cnm.cluster.fqdn Domain name
Accept application/json Accepted media type

URL parameters

Field Type Description
uid integer The role’s unique ID.

Response

Returns a role object.

Example JSON body

{
     "uid": 17,
     "name": "DBA",
     "management": "admin"
}

Status codes

Code Description
200 OK Success.
403 Forbidden Operation is forbidden.
404 Not Found Role does not exist.
501 Not Implemented Cluster doesn’t support roles yet.

Update role

PUT /v1/roles/{int: uid}

Update an existing role’s details.

Permissions

Permission name Roles
update_role admin

Request

Example HTTP request

PUT /roles/17

Example JSON body

{
     "management": "cluster_member"
}

Headers

Key Value Description
Host cnm.cluster.fqdn Domain name
Accept application/json Accepted media type

Body

Include a role object with updated fields in the request body.

Response

Returns a role object with the updated fields.

Example JSON body

{
     "uid": 17,
     "name": "DBA",
     "management": "cluster_member"
}

Error codes

Possible error_code values:

Code Description
unsupported_resource The cluster is not yet able to handle this resource type. This could happen in a partially upgraded cluster, where some of the nodes are still on a previous version.
name_already_exists An object of the same type and name exists.
change_last_admin_role_not_allowed At least one user with admin role should exist.

Status codes

Code Description
200 OK Success, role is created.
400 Bad Request Bad or missing configuration parameters.
404 Not Found Attempting to change a non-existant role.
501 Not Implemented Cluster doesn’t support roles yet.

Create role

POST /v1/roles

Create a new role.

Permissions

Permission name Roles
create_role admin

Request

Example HTTP request

POST /roles

Example JSON body

{
     "name": "DBA",
     "management": "admin"
}

Headers

Key Value Description
Host cnm.cluster.fqdn Domain name
Accept application/json Accepted media type

Body

Include a role object in the request body.

Response

Returns the newly created role object.

Example JSON body

{
     "uid": 17,
     "name": "DBA",
     "management": "admin"
}

Error codes

Possible error_codevalues:

Code Description
unsupported_resource The cluster is not yet able to handle this resource type. This could happen in a partially upgraded cluster, where some of the nodes are still on a previous version.
name_already_exists An object of the same type and name exists
missing_field A needed field is missing

Status codes

Code Description
200 OK Success, role is created.
400 Bad Request Bad or missing configuration parameters.
501 Not Implemented Cluster doesn’t support roles yet.

Examples

cURL

curl -k -u "[username]:[password]" -X POST \
     -H 'Content-Type: application/json' \
     -d '{ "name": "DBA", "management": "admin" }' \
     https://[host][:port]/v1/roles

Python

import requests
import json

url = "https://[host][:port]/v1/roles"

headers = {
  'Content-Type': 'application/json'
}

payload = json.dumps({
    "name": "DBA",
    "management": "admin"
})
auth=("[username]", "[password]")

response = requests.request("POST", url,
           auth=auth, headers=headers, payload=payload, verify=False)

print(response.text)

Delete role

DELETE /v1/roles/{int: uid}

Delete a role object.

Permissions

Permission name Roles
delete_role admin

Request

Example HTTP request

DELETE /roles/1

Headers

Key Value Description
Host cnm.cluster.fqdn Domain name
Accept application/json Accepted media type

URL parameters

Field Type Description
uid integer The role unique ID.

Response

Returns a status code to indicate role deletion success or failure.

Status codes

Code Description
200 OK Success, the role is deleted.
404 Not Found Role does not exist.
406 Not Acceptable The request is not acceptable.
501 Not Implemented Cluster doesn’t support roles yet.