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.

Required permissions

Permission name
view_all_roles_info

Request

Example HTTP request

GET /roles

Request 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.

Required permissions

Permission name
view_role_info

Request

Example HTTP request

GET /roles/1

Request 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.

Required permissions

Permission name
update_role

Request

Example HTTP request

PUT /roles/17

Example JSON body

{
     "management": "cluster_member"
}

Request headers

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

Request 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.

Required permissions

Permission name
create_role

Request

Example HTTP request

POST /roles

Example JSON body

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

Request headers

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

Request 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.

Delete role

DELETE /v1/roles/{int: uid}

Delete a role object.

Required permissions

Permission name
delete_role

Request

Example HTTP request

DELETE /roles/1

Request 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.