openproject/docs/api/apiv3/endpoints/roles.apib

# Group Roles

When principals (groups or users) are assigned to a project, they are receive roles in that project. Roles regulate access to specific resources by having permissions configured for them.

Currently, this is only a stub.

## Linked Properties
| Link                  | Description                               | Type          | Constraints                    | Supported operations |
| :-------------------: | ----------------------------------------- | ------------- | -------------------------------| -------------------- |
| self                  | This role                                 | Role          | not null                       | READ                 |

## Local Properties
| Property    | Description                                   | Type        | Constraints | Supported operations |
| :---------: | --------------------------------------------- | ----------- | ----------- | -------------------- |
| id          | Role id                                       | Integer     | x > 0       | READ                 |
| name        | Role name                                     | String      | not null    | READ                 |


## Role [/api/v3/roles/{id}]

+ Model
    + Body

            {
              "_type": "Role",
              "id": 3,
              "name": "Manager",
              "_links": {
                "self": {
                  "href": "/api/v3/roles/3",
                  "title": "Manager"
                }
              }
            }

## View role [GET]

Fetch an individual role.

+ Parameters
    + id (required, integer, `1`) ... role id

+ Response 200 (application/hal+json)

    [Role][]

+ Response 403 (application/hal+json)

    Returned if the client does not have sufficient permissions to see roles.

    **Required permission:** view members **or** manage members

    + Body

            {
                "_type": "Error",
                "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
                "message": "You are not authorized to view this resource."
            }

+ Response 404 (application/hal+json)

    Returned if the role does not exist.

    + Body

            {
                "_type": "Error",
                "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
                "message": "The requested resource could not be found."
            }

## Roles [/api/v3/roles{?filters}]

+ Model
    + Body

            {
              "_type": "Collection",
              "total": 5,
              "count": 5,
              "_embedded": {
                "elements": [
                  {
                    "_type": "Role",
                    "id": 3,
                    "name": "Manager",
                    "_links": {
                      "self": {
                        "href": "/api/v3/roles/3",
                        "title": "Manager"
                      }
                    }
                  },
                  {
                    "_type": "Role",
                    "id": 2,
                    "name": "Anonymous",
                    "_links": {
                      "self": {
                        "href": "/api/v3/roles/2",
                        "title": "Anonymous"
                      }
                    }
                  },
                  {
                    "_type": "Role",
                    "id": 5,
                    "name": "Reader",
                    "_links": {
                      "self": {
                        "href": "/api/v3/roles/5",
                        "title": "Reader"
                      }
                    }
                  },
                  {
                    "_type": "Role",
                    "id": 4,
                    "name": "Member",
                    "_links": {
                      "self": {
                        "href": "/api/v3/roles/4",
                        "title": "Member"
                      }
                    }
                  },
                  {
                    "_type": "Role",
                    "id": 1,
                    "name": "Non member",
                    "_links": {
                      "self": {
                        "href": "/api/v3/roles/1",
                        "title": "Non member"
                      }
                    }
                  }
                ]
              },
              "_links": {
                "self": {
                  "href": "/api/v3/roles"
                }
              }
            }

## List roles [GET]

List all defined roles. This includes built in roles like 'Anonymous' and 'Non member'.

+ Parameters
    + filters (optional, string, `[{ "unit": { "operator": "=", "values": ["system"] }" }]`) ... JSON specifying filter conditions.
    Accepts the same format as returned by the [queries](#queries) endpoint.
    Currently supported filters are:
      + grantable: filters roles based on whether they are selectable for a membership
      + unit: filters roles based on the unit ('project' or 'system') for which they are selectable for a membership

+ Response 200 (application/hal+json)

    [Roles][]