Roles /roles

You can manage user roles by using /roles endpoint. It provides user roles management: creation, data retrieval, modification, removal and user association.

Create a role

You can create role data by using POST /roles endpoint. Roles data must be specified inside body JSON data.

Request body structure is:

{
    "data": {
        "type": "roles",
        "attributes": {}
    }
}
POST /roles

Example request (create sample role):

POST /users HTTP/1.1
Host: example.com
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json

{
    "data": {
        "type": "roles",
        "attributes": {
            "name": "sample role"
        }
    }
}

Expected response is HTTP/1.1 201 OK, with application/vnd.api+json body data representing the role just created.

When role already exists or data is not valid (i.e. data lacks of required fields), POST fails and response is 400 Bad Request - Invalid data.

Successful response example follows:

HTTP/1.1 201 OK
Content-Type: application/vnd.api+json

{
    "data": {
        "id": "7",
        "type": "roles",
        "attributes": {
            "name": "sample role",
            "created": "2016-12-13T13:38:17+00:00",
            "modified": "2016-12-13T13:38:17+00:00"
        },
        "relationships": {
            "users": {
                "links": {
                    "related": "http://example.com/roles/1/users",
                    "self": "http://example.com/roles/7/relationships/users"
                }
            }
        }
    },
    "links": {
        "self": "http://example.com/roles",
        "home": "http://example.com/home"
    }
}

Get role data

You can obtain role data by using GET /roles and GET /roles/(role_id) endpoint.

GET /roles

It returns a collection of roles:

  • use id query string parameter to retrieve a single role by id
  • use id query string parameter and users token to retrieve users by role id
GET /roles/(role_id)

Example request (get roles):

GET /roles HTTP/1.1
Host: example.com
Accept: application/vnd.api+json

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
    "data": [
        {
            "id": 7,
            "type": "roles",
            "attributes": {
                "name": "sample role",
                "description": null,
                "unchangeable": false,
                "created": "2016-12-13T13:38:17+00:00",
                "modified": "2016-12-13T13:38:17+00:00"
            },
            "links": {
                "self": "http://example.com/roles/7"
            },
            "relationships": {
                "users": {
                    "links": {
                        "related": "http://example.com/roles/7/users",
                        "self": "http://example.com/roles/7/relationships/users"
                    }
                }
            }
        }
    ],
    "links": {
        "self": "http://example.com/roles",
        "home": "http://example.com/home",
        "first": "http://example.com/roles",
        "last": "http://example.com/roles",
        "prev": null,
        "next": null
    },
    "meta": {
        "pagination": {
            "count": 1,
            "page": 1,
            "page_count": 1,
            "page_items": 1,
            "page_size": 20
        }
    }
}
GET /roles/(role_id)/users

You can obtain role users by using GET /roles/(role_id)/users endpoint.

Example request (get users by role ‘sample role’, id 7):

GET /roles/7/users HTTP/1.1
Host: example.com
Accept: application/vnd.api+json

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
    "data": [
        {
            "id": "19283",
            "type": "users",
            "attributes": {
                "username": "johndoe",
            },
            "links": {
                "self": "http://example.com/users/19283"
            },
            "relationships": {
                "roles": {
                    "links": {
                        "related": "http://example.com/users/19283/roles",
                        "self": "http://example.com/users/19283/relationships/roles"
                    }
                }
            }
        }
    ],
    "links": {
        "self": "http://example.com/roles/7/users",
        "home": "http://example.com/home",
        "first": "http://example.com/roles/7/users",
        "last": "http://example.com/roles/7/users",
        "prev": null,
        "next": null
    },
    "meta": {
        "pagination": {
            "count": 1,
            "page": 1,
            "page_count": 1,
            "page_items": 1,
            "page_size": 20
        }
    }
}

Modify a role

You can modify a role by using PATCH /roles/(role_id) endpoint.

PATCH /roles

Example request (modify role ‘sample role’):

In this example, purpose is modifying ‘sample role’ name to ‘Dummy Role’.

PATCH /roles/7 HTTP/1.1
Host: example.com
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json

{
    "data": {
        "id": 7,
        "type": "roles",
        "attributes": {
            "name" : "Dummy Role"
        }
    }
}

Response 200 OK is expected.

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
    "data": {
       "id": 7,
        "type": "roles",
        "attributes": {
            "name": "Dummy Role",
            "description": null,
            "unchangeable": false,
            "created": "2016-12-13T13:38:17+00:00",
            "modified": "2016-12-13T14:02:37+00:00"
        },
        "relationships": {
            "users": {
                "links": {
                    "related": "http://example.com/roles/7/users",
                    "self": "http://example.com/roles/7/relationships/users"
                }
            }
        }
    },
    "links": {
        "self": "http://example.com/roles/7",
        "home": "http://example.com/home"
    }
}

Remove a role

You can delete a role by using DEL /roles/(role_id) endpoint.

DELETE /roles

Example request (delete role ‘Sample Role’, id 7):

DELETE /roles/7 HTTP/1.1
Host: example.com

Expected response is 204 No Content. When role is not found, response is 404 Not Found.

HTTP/1.1 204 No Content

Add a user role

You can add a role to a user by using POST /roles/(role_id)/relationships/users endpoint. (role_id) is a placeholder for role id. You specify user id inside JSON body passed to request.

POST /roles/(role_id)/relationships/users

Example request (add role 7 to john doe user, id 19283):

In this example, purpose is adding a role (id 7) to ‘johndoe’ user (id 19283).

POST /roles/7/relationships/users HTTP/1.1
Host: example.com
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json

{
    "data": {
        "type": "users",
        "id": 19283
    }
}

Response 200 OK is expected.

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
    "links": {
        "self": "http://example.com/roles/7/relationships/users",
        "home": "http://example.com/home"
    }
}

Remove a user role

You can remove a role from a user by using DELETE /roles/(role_id)/relationships/users endpoint. (role_id) is a placeholder for role id. You specify user id inside JSON body passed to request.

DELETE /roles/(role_id)/relationships/users

Example request (remove role 7 from john doe user, id 19283):

In this example, purpose is removing a role (id 7) from ‘johndoe’ user (id 19283).

DELETE /roles/7/relationships/users HTTP/1.1
Host: example.com
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json

{
    "data": {
        "type": "users",
        "id": 19283
    }
}

Response 200 OK is expected.

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
    "links": {
        "self": "http://example.com/roles/7/relationships/users",
        "home": "http://example.com/home"
    }
}