Skip to content

Latest commit

 

History

History
339 lines (286 loc) · 12.5 KB

roles.rst

File metadata and controls

339 lines (286 loc) · 12.5 KB
Raw

roles

GET

Retrieves all user :term:`Roles`.

Auth. Required:Yes
Roles Required:None
Permissions Required:ROLE:READ
Response Type:Array

Request Structure

Request Query Parameters
Name Required Description
id no Return only the :term:`Role` identified by this integral, unique identifier
name no Return only the :term:`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 response array
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 limit long and the first page is 1. If offset was defined, this query parameter has no effect. limit must be defined to make use of page. 
GET /api/4.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 :term:`Role`
description:A description of the :term:`Role`
name:The name of the :term:`Role`
lastUpdated:The date and time at which this :term:`Role` was last updated, in RFC 3339 format 
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 :term:`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 :term:`Role`[1]
description:A helpful description of the :term:`Role`'s purpose.
name:The name of the new :term:`Role` 
POST /api/4.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 :term:`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 :term:`Role`
name:

The name of the :term:`Role`
lastUpdated:

The date and time at which this :term:`Role` was last updated, in RFC 3339 format

 
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,
        "lastUpdated": "2021-05-03T14:50:18.93513-06:00"
}}

PUT

Replaces an existing :term:`Role` with one provided by the request[2].

Auth. Required:Yes
Roles Required:"admin"
Permissions Required:ROLE:UPDATE, ROLE:READ
Response Type:

Request Structure

Request Query Parameters
Name Required Description
name yes The name of the :term:`Role` to be updated
permissions:

An optional array of permission names that will be granted to the new :term:`Role`

Warning

When not present, the affected :term:`Role`'s Permissions will be unchanged - not removed, unlike when the array is empty.
description:

A helpful description of the :term:`Role`'s purpose.
name:

The new name of the :term:`Role`

 
PUT /api/4.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 :term:`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 be null, even if the :term:`Role` has Permissions that would have gone unchanged.
description:

A description of the :term:`Role`
name:

The name of the :term:`Role`
lastUpdated:

The date and time at which this :term:`Role` was last updated, in RFC 3339 format

 
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,
                "lastUpdated": "2021-05-03T14:50:18.93513-06:00"
        }
}

DELETE

Deletes a :term:`Role`[2].

Auth. Required:Yes
Roles Required:"admin"
Permissions Required:ROLE:DELETE, ROLE:READ
Response Type:undefined

Request Structure

Request Query Parameters
Name Required Description
name yes The name of the :term:`Role` to be deleted 
DELETE /api/4.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, if permissions is omitted or explicitly null, it is treated as an empty set/array.
[2](1, 2) The special :term:`Role` with the name "admin" cannot be modified or deleted - regardless of user Permissions.