Skip to main content

​
Overview

The Roles API provides endpoints to manage role catalog entries in the furniture store system. Roles are used for permission management and user profile assignment. Base URL: /roles

​
Endpoints

​
List Roles

Retrieve all active roles from the catalog. 
GET /roles/

​
Response

Returns an HTML page with the list of roles. For API consumption, roles are represented as:
​
id_role
integer
Unique identifier for the role
​
name
string
Name of the role (max 50 characters)
​
active
boolean
Whether the role is active
​
created_at
string
ISO 8601 timestamp of creation
​
updated_at
string
ISO 8601 timestamp of last update

​
Example Request

curl -X GET http://localhost:5000/roles/ \
  -H "Accept: text/html"

​
Example Response

[
  {
    "id_role": 1,
    "name": "Admin",
    "active": true,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  {
    "id_role": 2,
    "name": "Editor",
    "active": true,
    "created_at": "2024-01-16T14:20:00Z",
    "updated_at": "2024-01-16T14:20:00Z"
  },
  {
    "id_role": 3,
    "name": "Viewer",
    "active": true,
    "created_at": "2024-01-17T09:15:00Z",
    "updated_at": "2024-01-17T09:15:00Z"
  }
]

​
Create Role

Create a new role entry in the catalog. 
GET  /roles/create
POST /roles/create
GET - Displays the creation form POST - Processes form submission and creates the role

​
Request Parameters

​
name
string
required
Name of the roleValidation:
  • Required field
  • Maximum 50 characters
  • Must be unique

​
Response

Success:
  • Flash message: “Rol creado exitosamente”
  • Redirects to /roles/create
Error Cases:
​
ConflictError
error
Returned when a role with the same name already exists

​
Example Request

curl -X POST http://localhost:5000/roles/create \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "name=Manager" \
  -d "csrf_token=your_csrf_token"

​
Success Response

<!-- Flash message displayed -->
<div class="alert alert-success">
  Rol creado exitosamente
</div>

​
Error Response

<!-- Flash message displayed -->
<div class="alert alert-error">
  Ya existe un rol con ese nombre
</div>

​
Edit Role

Update an existing role in the catalog. 
GET  /roles/<id_role>/edit
POST /roles/<id_role>/edit
GET - Displays the edit form pre-populated with current data POST - Processes form submission and updates the role

​
Path Parameters

​
id_role
integer
required
Unique identifier of the role to edit

​
Request Parameters

​
name
string
required
Updated name for the roleValidation:
  • Required field
  • Maximum 50 characters
  • Must be unique

​
Response

Success:
  • Flash message: “Rol actualizado exitosamente”
  • Redirects to /roles/
Error Cases:
​
NotFoundError
error
Returned when the role ID does not existRedirects to /roles/ with error message
​
ConflictError
error
Returned when the updated name conflicts with an existing role
​
ValidationError
error
Returned when validation rules are violated

​
Example Request

curl -X POST http://localhost:5000/roles/1/edit \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "name=Super Admin" \
  -d "csrf_token=your_csrf_token"

​
Delete Role

Perform logical deletion of a role (marks as inactive). 
POST /roles/<id_role>/delete

​
Path Parameters

​
id_role
integer
required
Unique identifier of the role to delete

​
Response

Success:
  • Flash message: “Rol eliminado exitosamente”
  • Redirects to /roles/
Error Cases:
​
NotFoundError
error
Returned when the role ID does not existRedirects to /roles/ with error message

​
Example Request

curl -X POST http://localhost:5000/roles/1/delete \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "csrf_token=your_csrf_token"

​
Data Model

​
Role Object

{
  "id_role": 1,
  "name": "Admin",
  "active": true,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

​
Validation Rules

  • name: Required, unique, max 50 characters
  • active: Boolean, defaults to true
  • All endpoints require CSRF token for POST requests

​
Error Messages

ErrorMessage
Missing name”El nombre del rol es requerido”
Name too long”El nombre no puede exceder 50 caracteres”
Duplicate name”Ya existe un rol con ese nombre”
Not foundRole-specific error message from service

​
Implementation Details

  • Source: app/catalogs/roles/routes.py:13-104
  • Form: app/catalogs/roles/forms.py:10-19
  • Model: app/models/role.py:4-58
  • Pattern: Post-Redirect-Get (PRG) for all form submissions
  • Deletion: Logical (soft delete) - sets active=false and deleted_at timestamp

​
Common Role Examples

​
Typical Role Hierarchy

[
  {
    "name": "Super Admin",
    "description": "Full system access and configuration"
  },
  {
    "name": "Admin",
    "description": "Administrative access to most features"
  },
  {
    "name": "Manager",
    "description": "Manage products and orders"
  },
  {
    "name": "Editor",
    "description": "Edit content and catalog items"
  },
  {
    "name": "Viewer",
    "description": "Read-only access to system data"
  },
  {
    "name": "Customer",
    "description": "Standard customer access"
  }
]

​
Security Considerations

Deleting or modifying roles that are currently assigned to users may affect their access permissions. Ensure proper checks are in place before allowing role deletion.

​
Best Practices

  1. Use descriptive, self-explanatory role names (e.g., “Sales Manager” instead of “SM”)
  2. Maintain a clear role hierarchy with minimal overlap
  3. Avoid deleting roles that are actively assigned to users
  4. Consider implementing role permission mapping for fine-grained access control
  5. Regular audit of active roles and their assignments
Roles are typically used in conjunction with:
  • User management endpoints
  • Permission assignment endpoints
  • Access control middleware

Build docs developers (and LLMs) love

Get started for freeTalk to us