Gezondheids Meter API v3.0

What's New in v3.0

Major architectural improvements for better performance and simplicity

✨ Key Features

Option-Based Scoring: Questions now have predefined answer options with fixed points
Live Score Computation: All scores calculated on-demand from answers
Simplified API: Removed complex scoring rules and report tables
Better Performance: Optimized queries for faster response times

🔧 What Changed

❌ Removed

Scoring rules endpoints
Daily category scores
Weekly reports
Monthly reports
question_type field

✅ Added

question_options table
Live score computation
Trend endpoints
display_order for questions
Simplified data model

Quick Start Guide

1. Register & Login

# Register
curl -X POST http://localhost:8000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john_doe",
    "password": "secure_password",
    "email_address": "john@example.com"
  }'

# Login
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john_doe",
    "password": "secure_password"
  }'

2. Get Questions with Options

curl -X GET http://localhost:8000/api/questions \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "success": true,
  "data": {
    "questions": [
      {
        "question_id": 1,
        "question_text": "How did you sleep?",
        "category_name": "Physical Health",
        "options": [
          {"option_id": 1, "option_text": "Very well", "points": 5},
          {"option_id": 2, "option_text": "Well", "points": 4},
          {"option_id": 3, "option_text": "Fair", "points": 3},
          {"option_id": 4, "option_text": "Poorly", "points": 2},
          {"option_id": 5, "option_text": "Very poorly", "points": 1}
        ]
      }
    ]
  }
}

3. Submit Answer by Selecting Option

curl -X POST http://localhost:8000/api/answers \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "question_id": 1,
    "option_id": 2
  }'

4. Get Health Score

curl -X GET "http://localhost:8000/api/health-score?period=week" \
  -H "Authorization: Bearer YOUR_TOKEN"

Authentication

POST /auth/register

Register a new user account

{
  "username": "john_doe",
  "password": "secure_password",
  "email_address": "john@example.com"
}

POST /auth/login

Login and receive authentication token

{
  "username": "john_doe",
  "password": "secure_password"
}

Response:

{
  "success": true,
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGci...",
    "user": {
      "user_id": 1,
      "username": "john_doe",
      "role": "user"
    }
  }
}

POST /auth/logout

Logout and invalidate token

GET /auth/validate

Validate current authentication token

Questions & Options

Questions now always include their answer options with predefined points

🆕 Key Change: Each question now has a display_order field and includes an options array. The question_type field has been removed.

GET /questions

Get all questions with their answer options

Query Parameters:

category_id (optional) - Filter by category
search (optional) - Search in question text
limit (optional) - Default: 50
offset (optional) - Default: 0

Response:

{
  "success": true,
  "data": {
    "questions": [
      {
        "question_id": 1,
        "category_id": 1,
        "category_name": "Mental Health",
        "question_text": "How would you rate your stress level?",
        "display_order": 1,
        "options": [
          {"option_id": 1, "option_text": "No stress", "points": 5},
          {"option_id": 2, "option_text": "Mild stress", "points": 4},
          {"option_id": 3, "option_text": "Moderate stress", "points": 3},
          {"option_id": 4, "option_text": "High stress", "points": 2},
          {"option_id": 5, "option_text": "Severe stress", "points": 1}
        ]
      }
    ],
    "total": 20
  }
}

GET /questions/{id}

Get a single question with options

GET /categories/{id}/questions

Get all questions for a specific category

POST /questions Admin Only

Create a new question

{
  "category_id": 1,
  "question_text": "Did you exercise today?",
  "display_order": 5
}

Note: After creating a question, you must create options for it via database.

PUT /questions/{id} Admin Only

Update question (full replacement)

PATCH /questions/{id} Admin Only

Update question (partial)

DELETE /questions/{id} Admin Only

Delete question and all associated data

Answer Submission

🆕 Key Change: Submit answers by selecting an option_id instead of providing text. Points are automatically determined by the selected option.

POST /answers

Submit an answer by selecting an option

{
  "question_id": 1,
  "option_id": 3
}

Response:

{
  "success": true,
  "data": {
    "answer": {
      "answer_id": 123,
      "user_id": 1,
      "question_id": 1,
      "option_id": 3,
      "answer_date": "2026-01-29",
      "question_text": "How would you rate your stress level?",
      "option_text": "Moderate stress",
      "points": 3
    },
    "action": "created"
  }
}

💡 If you answer the same question twice on the same day, it updates the previous answer (action: "updated")

GET /answers/progress

Get completion progress and health scores

Response:

{
  "success": true,
  "data": {
    "overall": {
      "total_questions": 20,
      "answered_questions": 15,
      "answered_today": 15,
      "completion_percentage": 75.00,
      "health_percentage": 58.50
    },
    "by_category": [
      {
        "category_id": 1,
        "category_name": "Mental Health",
        "total_questions": 5,
        "answered_today": 5,
        "completion_percentage": 100.00,
        "health_percentage": 18.00
      }
    ]
  }
}

GET /answers/today

Get all answers submitted today

Query Parameters:

category_id (optional) - Filter by category

GET /answers/history

Get historical answer data for charts

Query Parameters:

period (required) - week, month, or year
category_id (optional) - Filter by category

Health Score

All scores are computed live from answers - no caching or stored reports

🆕 Key Change: Scores are calculated on-demand by summing points from selected options. No pre-calculated reports.

GET /health-score

Get overall health score for a time period

Query Parameters:

period (optional) - week or month (default: week)

Response:

{
  "success": true,
  "data": {
    "period": "week",
    "health_score": 425.50,
    "total_answers": 140,
    "days_answered": 7
  }
}

GET /health-score/by-category

Get health scores broken down by category

Query Parameters:

period (optional) - week or month (default: week)

GET /health-score/trend

Get trend data for charts and graphs

Query Parameters:

period (optional) - week, month, or 6months (default: week)

Response:

{
  "success": true,
  "data": {
    "period": "week",
    "trend": [
      {"period": "2026-01-23", "score": 58.50, "answers_count": 20},
      {"period": "2026-01-24", "score": 61.00, "answers_count": 20},
      {"period": "2026-01-25", "score": 59.50, "answers_count": 19}
    ]
  }
}

User Management

GET /users Admin Only

List all users

GET /users/{id}

Get user details

POST /users Admin Only

Create new user

PUT /users/{id}

Update user (full)

PATCH /users/{id}

Update user (partial)

PATCH /users/{id}/password

Change user password

DELETE /users/{id} Admin Only

Delete user

API Keys

POST /users/{id}/api-keys

Create API key for user

GET /users/{id}/api-keys

List user's API keys

DELETE /users/{id}/api-keys/{key_id}

Revoke API key

Admin Endpoints

GET /admin/stats Admin Only

Get system statistics

GET /admin/users/statistics Admin Only

Get user statistics

GET /admin/data/statistics Admin Only

Get data statistics

GET /admin/export/users Admin Only

Export user data (CSV or JSON)

GET /admin/reports/{type} Admin Only

Generate system reports (weekly or monthly)

POST /admin/notifications/send/{userId} Admin Only

Send notification to user

POST /users/{id}/reset Admin Only

Reset all user data

Migration Guide from v2.x

Frontend Changes Required

1. Question Rendering

// OLD (v2.x)
questions.forEach(q => {
  renderQuestion(q.question_content, q.question_type);
});

// NEW (v3.0)
questions.forEach(q => {
  renderQuestion(q.question_text, q.options);
  // Display options as radio buttons or select dropdown
  q.options.forEach(opt => {
    console.log(opt.option_text, opt.points);
  });
});

2. Answer Submission

// OLD (v2.x)
const answer = {
  question_id: 1,
  answer_content: "Often"
};

// NEW (v3.0)
const answer = {
  question_id: 1,
  option_id: selectedOptionId  // Get from user selection
};

fetch('/api/answers', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify(answer)
});

3. Health Score Display

// OLD (v2.x) - Fetch from stored reports
const report = await fetch('/api/users/1/weekly-reports/latest');

// NEW (v3.0) - Computed live
const score = await fetch('/api/health-score?period=week');
const byCategory = await fetch('/api/health-score/by-category?period=week');
const trend = await fetch('/api/health-score/trend?period=week');

4. Chart Data

// OLD (v2.x)
const weeklyData = await fetch('/api/users/1/weekly-reports');

// NEW (v3.0)
const trendData = await fetch('/api/health-score/trend?period=week');
// Use trendData.data.trend for chart

⚠️ Removed Endpoints

The following endpoints have been permanently removed:

/scoring-rules/*
/users/{id}/daily-scores/*
/users/{id}/weekly-reports/*
/users/{id}/monthly-reports/*

Replace with live computed endpoints: /health-score, /health-score/by-category, /health-score/trend

Complete Endpoint Reference

Method	Endpoint	Auth	Description
Authentication
POST	/auth/register	No	Register new user
POST	/auth/login	No	Login and get token
POST	/auth/logout	Yes	Logout
GET	/auth/validate	Yes	Validate token
Questions
GET	/questions	Yes	List questions with options
GET	/questions/{id}	Yes	Get question with options
POST	/questions	Admin	Create question
PUT	/questions/{id}	Admin	Update question
PATCH	/questions/{id}	Admin	Partial update
DELETE	/questions/{id}	Admin	Delete question
Answers
POST	/answers	Yes	Submit answer (option_id)
GET	/answers/progress	Yes	Get progress
GET	/answers/today	Yes	Today's answers
GET	/answers/history	Yes	Historical data
Health Score
GET	/health-score	Yes	Overall score
GET	/health-score/by-category	Yes	Scores by category
GET	/health-score/trend	Yes	Trend data
Users
GET	/users	Admin	List users
GET	/users/{id}	Yes	Get user
POST	/users	Admin	Create user
PUT	/users/{id}	Yes	Update user
PATCH	/users/{id}	Yes	Partial update
DELETE	/users/{id}	Admin	Delete user
Categories
GET	/categories	Yes	List categories
GET	/categories/{id}	Yes	Get category
POST	/categories	Admin	Create category
Admin
GET	/admin/stats	Admin	System statistics
GET	/admin/users/statistics	Admin	User statistics
GET	/admin/data/statistics	Admin	Data statistics
GET	/admin/export/users	Admin	Export users
GET	/admin/reports/{type}	Admin	Generate report

Gezondheids Meter API

Breaking Changes in v3.0

Navigation

What's New in v3.0

✨ Key Features

🔧 What Changed

❌ Removed

✅ Added

Quick Start Guide

1. Register & Login

2. Get Questions with Options

3. Submit Answer by Selecting Option

4. Get Health Score

Authentication

Questions & Options

Answer Submission

Health Score

User Management

API Keys

Categories

Admin Endpoints

Migration Guide from v2.x

Frontend Changes Required

1. Question Rendering

2. Answer Submission

3. Health Score Display

4. Chart Data

⚠️ Removed Endpoints

Complete Endpoint Reference