Skip to main content

​
GET /api/roles/search

Performs a paginated search of roles with optional filtering by name. This endpoint is useful for displaying roles in a table or list with pagination controls.

​
Authentication

This endpoint requires authentication. Include a valid JWT token in the Authorization header.

​
Query Parameters

​
name
string
Optional filter to search for roles by name. Performs a partial match.
  • Example: "admin" will match “Administrator”, “Admin”, “System Admin”
​
page
integer
default:"0"
The page number to retrieve (zero-based index).
  • Minimum: 0
  • Example: 0 for the first page, 1 for the second page
​
size
integer
default:"10"
The number of results per page.
  • Default: 10
  • Example: 20 to retrieve 20 roles per page

​
Response

​
content
array
Array of role objects matching the search criteria
​
id
UUID
Unique identifier of the role
​
name
string
The name of the role
​
description
string
The description of the role
​
permissions
array
List of permissions assigned to this role
​
status
string
Current status of the role (ACTIVE, INACTIVE)
​
pageNumber
integer
Current page number (zero-based)
​
pageSize
integer
Number of items per page
​
totalElements
long
Total number of roles matching the search criteria
​
totalPages
integer
Total number of pages available
​
isLast
boolean
Indicates whether this is the last page

​
Error Responses

  • 400 Bad Request: Invalid parameters (e.g., negative page number, invalid size)
  • 500 Internal Server Error: Unexpected server error

​
Example Request

curl -X GET "https://api.example.com/api/roles/search?name=admin&page=0&size=10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Example Response

{
  "content": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Administrator",
      "description": "Full system access with all permissions",
      "permissions": [
        {
          "id": "660e8400-e29b-41d4-a716-446655440001",
          "name": "users:write",
          "description": "Permission to create and modify users",
          "status": "ACTIVE"
        }
      ],
      "status": "ACTIVE"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "name": "System Admin",
      "description": "System administration role",
      "permissions": [],
      "status": "ACTIVE"
    }
  ],
  "pageNumber": 0,
  "pageSize": 10,
  "totalElements": 2,
  "totalPages": 1,
  "isLast": true
}

​
Example Error Response

{
  "timestamp": "2024-01-15T10:30:00Z",
  "requestId": "abc-123-def",
  "message": "Invalid parameters",
  "detail": "Page number must be greater than or equal to 0"
}

​
Usage Notes

  • Use the name parameter for type-ahead search functionality
  • The search is case-insensitive and performs partial matching
  • Calculate the next page by incrementing pageNumber until isLast is true
  • Use totalElements and totalPages for pagination UI components

Build docs developers (and LLMs) love

Get started for freeTalk to us