Gezondheids Meter API

API Endpoints

Controllers

100%

Complete

Database Ready

Quick Start

Get the API running in 2 simple steps:

# 1. Start the server
php -S localhost:8000 -t public

# 2. Test the API
php test_api.php

# Or visit in browser
http://localhost:8000/api/health

Base URL: http://localhost:8000/api

Key Features

JWT Authentication

Secure token-based authentication with bcrypt password hashing

Role-Based Access

Super admin and party admin permissions

Auto-Generation

Automatic party answers, codes, and admin accounts

Political Compass

Calculate party positions on 2D compass

Party Matching

Find top 3 party matches for users

File Uploads

Profile pictures and party logos with auto-cleanup

Bulk Operations

Transaction-based bulk updates

Statistics

Comprehensive analytics and reporting

Empty Answer Support

Track unanswered questions with empty string state

API Endpoints

Tip: Click on any endpoint card to view detailed request/response examples, including authentication requirements and sample data.

Authentication (4 endpoints)

POST /auth/login No Auth

Authenticate user with username or email and receive token

Request Body (with username)

{
  "username": "testuser",
  "password": "password123"
}

Request Body (with email)

{
  "email_address": "test@example.com",
  "password": "password123"
}

Example Response (200 OK)

{
  "status": "success",
  "message": "Login successful",
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "user": {
      "user_id": 1,
      "username": "testuser",
      "role": "user"
    }
  }
}

Error Response (401 Unauthorized)

{
  "status": "error",
  "message": "Invalid credentials",
  "timestamp": "2024-12-04T12:00:00+00:00",
  "status_code": 401
}

POST /auth/register No Auth

Request Body

{
  "username": "newuser",
  "password": "securepassword123",
  "email_address": "newuser@example.com"
}

Example Response (201 Created)

{
  "status": "success",
  "message": "user account created successfully",
  "data": {
    "user_id": 2,
    "username": "newuser",
    "email_address": "newuser@example.com",
    "role": "user",
    "profile_url": null,
    "date_created": "2025-12-03 11:30:00"
  }
}

Error Response (400 Bad Request)

{
  "status": "error",
  "message": "Username already exists"
}

POST /auth/logout Auth Required

Invalidate authentication token

Headers

Authorization: Bearer {your_token}

Example Response (200 OK)

{
  "status": "success",
  "message": "Logged out successfully",
  "data": null
}

Error Response (400 Bad Request)

{
  "status": "error",
  "message": "Token not provided"
}

GET /auth/validate Auth Required

Validate current token and get user info

Headers

Authorization: Bearer {your_token}

Example Response (200 OK)

{
  "status": "success",
  "message": "Token is valid",
  "data": {
    "user_id": 1,
    "role": "user",
    "expires_at": "2025-12-04 10:00:00"
  }
}

Error Response (401 Unauthorized)

{
  "status": "error",
  "message": "Invalid or expired token"
}

User Management (7 endpoints)

GET /users Auth Required - Admin Only

List all users with filtering and pagination

Query Parameters

role: Filter by role (user|admin)
search: Search by username
limit: Results per page (default: 50)
offset: Results to skip (default: 0)

Example Response (200 OK)

{
  "status": "success",
  "message": "Users retrieved successfully",
  "data": {
    "users": [
      {
        "user_id": 1,
        "role": "user",
        "username": "john",
        "email_address": "john@example.com",
        "profile_url": "http://...",
        "patient_number": null,
        "date_created": "2024-01-01 12:00:00"
      }
    ],
    "total": 100,
    "limit": 50,
    "offset": 0
  }
}

GET /users/{id} Auth Required

Get a single user by ID (own profile or admin)

Example Response (200 OK)

{
  "status": "success",
  "message": "User retrieved successfully",
  "data": {
    "user_id": 1,
    "role": "user",
    "username": "john",
    "email_address": "john@example.com",
    "profile_url": "http://...",
    "patient_number": null,
    "date_created": "2024-01-01 12:00:00"
  }
}

Error Response (404 Not Found)

{
  "status": "error",
  "message": "User not found",
  "timestamp": "2024-12-04T12:00:00+00:00",
  "status_code": 404
}

POST /users Auth Required - Admin Only

Create a new user

Request Body

{
  "role": "user",
  "username": "john",
  "email_address": "john@example.com",
  "password": "password123",
  "profile_url": null,
  "patient_number": null
}

Example Response (200 OK)

{
  "status": "success",
  "message": "User created successfully",
  "data": {
    "message": "User created",
    "user_id": 1
  }
}

Validation Error (422)

{
  "status": "error",
  "message": "Validation failed",
  "timestamp": "2024-12-04T12:00:00+00:00",
  "status_code": 422,
  "errors": {
    "username": "Username is required",
    "email_address": "Invalid email address format",
    "password": "Password must be at least 6 characters"
  }
}

PUT /users/{id} Auth Required - Admin Only

Update user (full replacement)

Request Body

{
  "role": "admin",
  "username": "updated",
  "email_address": "updated@example.com",
  "profile_url": "http://...",
  "patient_number": 88
}

Example Response (200 OK)

{
  "status": "success",
  "message": "User updated successfully",
  "data": {
    "message": "User updated"
  }
}

PATCH /users/{id} Auth Required

Update user (partial update - own profile or admin)

Request Body (example)

{
  "profile_url": "https://newimage.com/me.png"
}

Allowed Fields

role, username, email_address, profile_url, patient_number

Example Response (200 OK)

{
  "status": "success",
  "message": "User updated successfully",
  "data": {
    "message": "User updated"
  }
}

PATCH /users/{id}/password Auth Required

Change user password (own password or admin)

Request Body

{
  "old_password": "old123",
  "new_password": "new123"
}

Example Response (200 OK)

{
  "status": "success",
  "message": "Password updated successfully",
  "data": {
    "message": "Password updated"
  }
}

Error Response (401 Unauthorized)

{
  "status": "error",
  "message": "Old password is incorrect",
  "timestamp": "2024-12-04T12:00:00+00:00",
  "status_code": 401
}

DELETE /users/{id} Auth Required - Admin Only

Delete a user

Example Response (200 OK)

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

Note

Cascading deletes will remove all related records.

Quick Start

Key Features

API Endpoints

Authentication (4 endpoints)

User Management (7 endpoints)

Error Response Format

Documentation

API Specification

API Worksheet