roles
GET
Retrieves all user Roles.
- Auth. Required
Yes
- Roles Required
None
- Permissions Required
ROLE:READ
- Response Type
Array
Request Structure
Name |
Required |
Description |
---|---|---|
id |
no |
Return only the Role identified by this integral, unique identifier |
name |
no |
Return only the Role with this name |
orderby |
no |
Choose the ordering of the results - must be the name of one of the fields of the objects in the |
sortOrder |
no |
Changes the order of sorting. Either ascending (default or “asc”) or descending (“desc”) |
limit |
no |
Choose the maximum number of results to return |
offset |
no |
The number of results to skip before beginning to return results. Must use in conjunction with limit |
page |
no |
Return the nth page of results, where “n” is the value of this parameter, pages are |
GET /api/5.0/roles?name=read-only HTTP/1.1
Host: trafficops.infra.ciab.test
User-Agent: curl/7.47.0
Accept: */*
Cookie: mojolicious=...
Response Structure
- permissions
An array of the names of the Permissions given to this Role
- description
A description of the Role
- id
The integral, unique identifier for this Role
- name
The name of the Role
HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie
Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
Access-Control-Allow-Origin: *
Content-Type: application/json
Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly
Whole-Content-Sha512: TEDXlQqWMSnJbL10JtFdbw0nqciNpjc4bd6m7iAB8aymakWeF+ghs1k5LayjdzHcjeDE8UNF/HXSxOFvoLFEuA==
X-Server-Name: traffic_ops_golang/
Date: Wed, 25 Aug 2021 20:10:34 GMT
Content-Length: 888
{ "response": [
{
"name": "read-only",
"description": "Has access to all read capabilities",
"permissions": [
"auth",
"api-endpoints-read",
"asns-read",
"cache-config-files-read",
"cache-groups-read",
"capabilities-read",
"cdns-read",
"cdn-security-keys-read",
"change-logs-read",
"consistenthash-read",
"coordinates-read",
"delivery-services-read",
"delivery-service-security-keys-read",
"delivery-service-requests-read",
"delivery-service-servers-read",
"divisions-read",
"to-extensions-read",
"federations-read",
"hwinfo-read",
"jobs-read",
"origins-read",
"parameters-read",
"phys-locations-read",
"profiles-read",
"regions-read",
"roles-read",
"server-capabilities-read",
"servers-read",
"service-categories-read",
"stats-read",
"statuses-read",
"static-dns-entries-read",
"steering-read",
"steering-targets-read",
"system-info-read",
"tenants-read",
"types-read",
"users-read"
],
"lastUpdated": "2021-05-03T14:50:18.93513-06:00",
}
]}
POST
Creates a new Role.
- Auth. Required
Yes
- Roles Required
“admin”
- Permissions Required
ROLE:CREATE, ROLE:READ
- Response Type
Object
Request Structure
- permissions
An optional array of permission names that will be granted to the new Role1
- description
A helpful description of the Role’s purpose.
- name
The name of the new Role
POST /api/5.0/roles HTTP/1.1
Host: trafficops.infra.ciab.test
User-Agent: curl/7.47.0
Accept: */*
Cookie: mojolicious=...
Content-Length: 56
Content-Type: application/json
{
"name": "test",
"description": "quest"
}
Response Structure
- permissions
An array of the names of the Permissions given to this Role
Tip
This can be
null
or empty, depending on whether it was present in the request body, or merely empty. Obviously, it can also be a populated array.- description
A description of the Role
- id
The integral, unique identifier for this Role
- name
The name of the Role
HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie
Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
Access-Control-Allow-Origin: *
Content-Type: application/json
Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly
Whole-Content-Sha512: gzfc7m/in5vVsVP+Y9h6JJfDhgpXKn9VAzoiPENhKbQfP8Q6jug08Rt2AK/3Nz1cx5zZ8P9IjVxDdIg7mlC8bw==
X-Server-Name: traffic_ops_golang/
Date: Wed, 04 Sep 2019 17:44:42 GMT
Content-Length: 128
{ "alerts": [{
"text": "role was created.",
"level": "success"
}],
"response": {
"name": "test",
"description": "quest",
"permissions": null
}}
PUT
Replaces an existing Role with one provided by the request2.
- Auth. Required
Yes
- Roles Required
“admin”
- Permissions Required
ROLE:UPDATE, ROLE:READ
- Response Type
Request Structure
Name |
Required |
Description |
---|---|---|
name |
yes |
The name of the Role to be updated |
- permissions
An optional array of permission names that will be granted to the new Role
Warning
When not present, the affected Role’s Permissions will be unchanged - not removed, unlike when the array is empty.
- description
A helpful description of the Role’s purpose.
- name
The new name of the Role
PUT /api/5.0/roles?name=test HTTP/1.1
Host: trafficops.infra.ciab.test
User-Agent: curl/7.47.0
Accept: */*
Cookie: mojolicious=...
Content-Length: 56
Content-Type: application/json
{
"name":"test",
"description": "quest_updated"
}
Response Structure
- permissions
An array of the names of the Permissions given to this Role
Tip
This can be
null
or empty, depending on whether it was present in the request body, or merely empty. Obviously, it can also be a populated array.Warning
If no
permissions
array was given in the request, this will always benull
, even if the Role has Permissions that would have gone unchanged.- description
A description of the Role
- name
The name of the Role
HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie
Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
Access-Control-Allow-Origin: *
Content-Type: application/json
Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly
Whole-Content-Sha512: mlHQenE1Q3gjrIK2lC2hfueQOaTCpdYEfboN0A9vYPUIwTiaF5ZaAMPQBdfGyiAhgHRxowITs3bR7s1L++oFTQ==
X-Server-Name: traffic_ops_golang/
Date: Thu, 05 Sep 2019 12:56:46 GMT
Content-Length: 136
{
"alerts": [
{
"text": "role was updated.",
"level": "success"
}
],
"response": {
"name": "test",
"description": "quest_updated",
"permissions": null
}
}
DELETE
- Auth. Required
Yes
- Roles Required
“admin”
- Permissions Required
ROLE:DELETE, ROLE:READ
- Response Type
undefined
Request Structure
Name |
Required |
Description |
---|---|---|
name |
yes |
The name of the Role to be deleted |
DELETE /api/5.0/roles?name=test HTTP/1.1
Host: trafficops.infra.ciab.test
User-Agent: curl/7.47.0
Accept: */*
Cookie: mojolicious=...
Response Structure
HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie
Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
Access-Control-Allow-Origin: *
Content-Type: application/json
Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly
Whole-Content-Sha512: 10jeFZihtbvAus/XyHAW8rhgS9JBD+X/ezCp1iExYkEcHxN4gjr1L6x8zDFXORueBSlFldgtbWKT7QsmwCHUWA==
X-Server-Name: traffic_ops_golang/
Date: Thu, 05 Sep 2019 13:02:06 GMT
Content-Length: 60
{ "alerts": [{
"text": "role was deleted.",
"level": "success"
}]}
- 1
permissions
cannot include permissions that are not included in the permissions of the requesting user. In POST requests, ifpermissions
is omitted or explicitlynull
, it is treated as an empty set/array.- 2(1,2)
The special Role with the name “admin” cannot be modified or deleted - regardless of user Permissions.