You can manage user roles by using /roles
endpoint.
It provides user roles management: creation, data retrieval, modification, removal and user association.
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": {}
}
}
.. http: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"
}
}
You can obtain role data by using GET /roles
and GET /roles/(role_id)
endpoint.
.. http: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 andusers
token to retrieve users by role id
.. http: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
}
}
}
.. http: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
}
}
}
You can modify a role by using PATCH /roles/(role_id)
endpoint.
.. http: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"
}
}
You can delete a role by using DEL /roles/(role_id)
endpoint.
.. http: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
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.
.. http: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"
}
}
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.
.. http: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"
}
}