Roles API

v1.0 • REST • JSON

Full CRUD management for roles. Create, retrieve, update, patch, and delete role records with support for user assignment tracking.

GET POST PUT PATCH DELETE 6 Endpoints Auth Required
Base URL https://bogusapi.com/api/roles

Quick Reference

GET
/api/roles List all roles
200 GET
/api/roles/{id} Get one role by ID
200 POST
/api/roles Create a new role
201 PUT
/api/roles/{id} Replace role data
204 PATCH
/api/roles/{id} Partially update a role
204 DEL
/api/roles/{id} Remove a role
204 GET
/api/roles/{id} Role not found example
404
GET /api/roles 200 OK

Get All Roles

Retrieves the complete list of roles available in the system. Each role includes its name, description, and the number of users currently assigned to it.

Headers
Authorization : Bearer 0a74625f-db42-42f8-b557-72b1ded72517....
Response: 200 OK
GET /api/roles/{id} 200 OK

Get Single Role

Fetches full details for a specific role by its numeric ID, including name, description, and user count.

Path Parameters
ParameterTypeRequiredDescription
id integer Required Unique role identifier
Headers
Authorization : Bearer 4376824f-6dcc-4fda-97f4-dccc1094c1e5....
Response: 200 OK
GET /api/roles/{id} 404 Not Found

Role Not Found

Returned when the requested role ID does not exist in the system. Use this example to test error-handling logic and build graceful fallback UI for missing role resources.

Headers
Authorization : Bearer 617ec716-ca45-49e8-ac87-c88c628b0570....
Response: 404 Not Found 
{}
POST /api/roles 201 Created

Create Role

Registers a new role with a name and description. On success, returns the newly created role object including the auto-generated ID.

Request Body
FieldTypeRequiredDescription
name string Required Unique role name
description string Required Human-readable description of the role 
Authorization : Bearer a40d5b26-b71f-4244-a5a2-18f9881e8912....
Response: 201 Created
PUT /api/roles/{id} 200 OK

Update Role

Fully replaces an existing role's data with the values in the request body. A successful update returns 200 OK with response body.

Request Body
FieldTypeRequiredDescription
name string Required Updated role name
description string Required Updated role description 
Authorization : Bearer b2a77047-1166-4d83-b4ea-e04b8c5dcea1....
Response: 200 OK
PATCH /api/roles/{id} 200 OK

Patch Role

Applies a partial update to an existing role using a JSON Patch (RFC 6902) document. Only the fields specified in the patch operations are modified. Returns 200 OK with response body on success.

Request Body

Array of JSON Patch operations. Supported operation: replace.

FieldTypeRequiredDescription
op string Required Operation type, e.g. replace
path string Required JSON Pointer to the field, e.g. /name
value any Required The new value for the field 
Content-Type : application/json-patch+json
Authorization : Bearer 79d66e70-7606-420a-8aaf-29113a138c47....
Response: 200 OK
DELETE /api/roles/{id} 204 No Content

Delete Role

Permanently removes a role from the system by its ID. This action is irreversible � once deleted, the role record cannot be recovered through the API.

Path Parameters
ParameterTypeRequiredDescription
id integer Required ID of the role to delete
Headers
Authorization : Bearer 8ee93fef-9298-45e6-9b47-eed8b5ffb130....
Response: 204 No Content 
{}