clqms-be/openspec/changes/archive/2026-03-08-backend-specs/user-api.md

User Management API

Overview

Create a complete User CRUD API for the user management page.

Required Endpoints

Method	Endpoint	Description
GET	/api/users	List all users (with pagination)
GET	/api/users/(:num)	Get single user by ID
POST	/api/users	Create new user
PATCH	/api/users	Update existing user
DELETE	/api/users/(:num)	Delete user

Database Schema

The User model should use the existing users table (or create if doesn't exist):

-- If table doesn't exist, create it:
CREATE TABLE IF NOT EXISTS users (
    UserID INT AUTO_INCREMENT PRIMARY KEY,
    Username VARCHAR(50) NOT NULL UNIQUE,
    Email VARCHAR(100) NOT NULL,
    Name VARCHAR(100),
    Role VARCHAR(50),
    Department VARCHAR(100),
    IsActive BOOLEAN DEFAULT TRUE,
    CreatedAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    UpdatedAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    DelDate TIMESTAMP NULL,
    INDEX idx_username (Username),
    INDEX idx_email (Email)
);

User Fields

Required Fields

• Username - Unique login username
• Email - User email address

Optional Fields

• Name - Full name
• Role - User role (admin, technician, doctor, etc.)
• Department - Department name
• IsActive - Whether user is active

API Specifications

1. List Users

Request:

GET /api/users?page=1&per_page=20&search=john HTTP/1.1

Query Parameters:

• page - Page number (default: 1)
• per_page - Items per page (default: 20)
• search - Search term for username/email/name (optional)

Success Response (200):

{
  "status": "success",
  "message": "Users retrieved successfully",
  "data": {
    "users": [
      {
        "UserID": 1,
        "Username": "john.doe",
        "Email": "john@hospital.com",
        "Name": "John Doe",
        "Role": "technician",
        "Department": "Laboratory",
        "IsActive": true,
        "CreatedAt": "2024-01-15 10:30:00"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 20,
      "total": 150,
      "total_pages": 8
    }
  }
}

2. Get Single User

Request:

GET /api/users/1 HTTP/1.1

Success Response (200):

{
  "status": "success",
  "message": "User retrieved successfully",
  "data": {
    "UserID": 1,
    "Username": "john.doe",
    "Email": "john@hospital.com",
    "Name": "John Doe",
    "Role": "technician",
    "Department": "Laboratory",
    "IsActive": true,
    "CreatedAt": "2024-01-15 10:30:00",
    "UpdatedAt": "2024-01-15 10:30:00"
  }
}

Not Found Response (404):

{
  "status": "failed",
  "message": "User not found",
  "data": null
}

3. Create User

Request:

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

{
  "Username": "jane.smith",
  "Email": "jane@hospital.com",
  "Name": "Jane Smith",
  "Role": "doctor",
  "Department": "Pathology"
}

Success Response (201):

{
  "status": "success",
  "message": "User created successfully",
  "data": {
    "UserID": 2,
    "Username": "jane.smith",
    "Email": "jane@hospital.com"
  }
}

Validation Error Response (400):

{
  "status": "failed",
  "message": "Validation failed",
  "data": {
    "Username": "Username is required",
    "Email": "Email is required"
  }
}

4. Update User

Request:

PATCH /api/users HTTP/1.1
Content-Type: application/json

{
  "UserID": 1,
  "Name": "John Doe Updated",
  "Role": "senior_technician"
}

Success Response (200):

{
  "status": "success",
  "message": "User updated successfully",
  "data": {
    "UserID": 1,
    "Name": "John Doe Updated",
    "Role": "senior_technician"
  }
}

5. Delete User

Request:

DELETE /api/users/1 HTTP/1.1

Success Response (200):

{
  "status": "success",
  "message": "User deleted successfully",
  "data": {
    "UserID": 1
  }
}

Implementation Files

See code-templates/ folder for ready-to-use code:

• UserController.php - Complete controller implementation
• UserModel.php - Database model
• Routes-additions.php - Routes to add to Routes.php

Testing

After implementation, test with:

# List users
curl http://localhost:8000/api/users

# Get single user
curl http://localhost:8000/api/users/1

# Create user
curl -X POST http://localhost:8000/api/users \
  -H "Content-Type: application/json" \
  -d '{"Username":"test","Email":"test@test.com","Name":"Test User"}'

# Update user
curl -X PATCH http://localhost:8000/api/users \
  -H "Content-Type: application/json" \
  -d '{"UserID":1,"Name":"Updated Name"}'

# Delete user
curl -X DELETE http://localhost:8000/api/users/1