Roles API

Each user has assigned one or more roles which provide system access based on granted permissions.

Content

Roles collection:

• [POST] create role
• [GET] index, searching and filtering roles

Single role:

• [GET] role detail
• [PUT/PATCH] update role
• [DELETE] delete role

Role permissions:

• See role permissions documentation page

Roles collection

Create role

POST /api/roles

This method needs permission create on permissions.

Method for creating new Role.

Request

Param	Type	Description	Requirements
name	string	Role name	Required. Has to be string. Max length is 50 chars.
is_active	boolean	Activity flag	Required. Has to be boolean.
role_permissions	RolePermissions[]	Role permissions	Present. Has to be array of unique RolePermissions objects or empty array.

RolePermissions

Param	Type	Description	Requirements
module_id	string	Module	Required. Must be valid identifier of existing Module.
permissions	PermissionEnum[]	Permissions	Present. Has to be array of unique PermissionEnum values or empty array.

POST /api/roles HTTP/1.1
Content-Type: application/json

{
    "name": "Uživatelé",
    "is_active": true,
    "role_permissions": [
        {
            "module_id": "products",
            "permissions": [
                "read", "create", "update" 
            ]
        }
    ]
}

Response

201 CREATED

POST /api/roles HTTP/1.1
Content-Type: application/json

{
    "id": 3,
    "name": "Uživatelé",
    "is_active": true,
    "is_protected": false,
    "_links": [
        {
            "href": "/api/roles/3",
            "rel": "self",
            "type": "GET"
        }
    ]
}

422 UNPROCESSABLE ENTITY

Validation error occurred.

POST /api/roles HTTP/1.1
Content-Type: application/json

{
    "type" : "ValidationError",
    "message" : "The given data was invalid.",
    "id" : "fe1b04de-b347-43b5-8118-864c1eefaccf",
    "errors": [
        {
            "field": "name",
            "message": "The name field is required."
        }
    ]
}

---

Roles index

This method needs permission read on users.

Request

Index behaviour	Definition
Paginated by default	No
Sorting	id, name, is_active, is_protected
Filters	id:enum, name:string, is_active:bool, is_protected:bool
Embedded	-

GET /api/roles HTTP/1.1
Content-Type: application/json

Response

200 OK

GET /api/roles HTTP/1.1
Content-Type: application/json

{
    "items": [
        {
            "id": 1,
            "name": "Administrator",
            "is_active": true,
            "is_protected": true,
            "_links": [
                {
                    "href": "/api/roles/1",
                    "rel": "self",
                    "type": "GET"
                }
            ]
        }
    ]
}

---

---

Single role

Role detail

GET /api/roles/{role_id}

This method needs permission read on users.

Get Role detail.

Request

Index behaviour	Definition
Embedded	-

Request

GET /api/roles/1 HTTP/1.1
Content-Type: application/json

Response

200 OK

GET /api/roles/1 HTTP/1.1
Content-Type: application/json

{
    "id": 1,
    "name": "Administrator",
    "is_active": true,
    "is_protected": true,
    "_links": [
        {
            "href": "/api/roles/1",
            "rel": "self",
            "type": "GET"
        }
    ]
}

404 NOT FOUND

Role was not found.

GET /api/roles/2 HTTP/1.1
Content-Type: application/json
Status-Code: 404

{
    "type": "NotFound",
    "message": "Required model was not found.",
    "id": "0cd85449-05fe-4866-9802-8192e6785fc7"
}

---

Update role

PUT/PATCH /api/roles/{role_id}

This method needs permission update on permissions.

Method for updating Role data.

Request

Same inputs and requirements as for POST method.

For PATCH method any field can be omitted.

PUT /api/roles/3 HTTP/1.1
Content-Type: application/json

{
    "name": "Zákazníci",
    "is_active": false,
    "role_permissions": [
            {
                "module_id": "products",
                "permissions": [
                    "full" 
                ]
            }
        ]
}

Response

200 OK

Role successfully updated.

PUT /api/roles/3 HTTP/1.1
Content-Type: application/json

{
    "id": 3,
    "name": "Zákazníci",
    "is_active": false,
    "is_protected": false,
    "_links": [
        {
            "href": "/api/roles/3",
            "rel": "self",
            "type": "GET"
        }
    ]
}

404 NOT FOUND

Role was not found.

PUT /api/roles/2 HTTP/1.1
Content-Type: application/json
Status-Code: 404

{
    "type": "NotFound",
    "message": "Required model was not found.",
    "id": "0cd85449-05fe-4866-9802-8192e6785fc7"
}

422 UNPROCESSABLE ENTITY

Validation error occurred.

POST /api/roles HTTP/1.1
Content-Type: application/json

{
    "type" : "ValidationError",
    "message" : "The given data was invalid.",
    "id" : "fe1b04de-b347-43b5-8118-864c1eefaccf",
    "errors": [
        {
            "field": "name",
            "message": "The name field is required."
        }
    ]
}

Delete role

DELETE /api/roles/{role_id}

This method needs permission delete on permissions.

Method for deleting Role.

Request

DELETE /api/roles/3 HTTP/1.1
Content-Type: application/json

Response

204 NO CONTENT

Role successfully deleted.

404 NOT FOUND

Role was not found.

DELETE /api/roles/2 HTTP/1.1
Content-Type: application/json
Status-Code: 404

{
    "type": "NotFound",
    "message": "Required model was not found.",
    "id": "0cd85449-05fe-4866-9802-8192e6785fc7"
}