IdeaArmour > Redis Enterprise Software > Reference > REST API > Requests > roles

Roles requests

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.

Edit on GitHub

Updated: September 17, 2024

Top