{ "version": "1.0", "modules": [ { "name": "User Management", "prefix": "/users", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create User Account", "description": "Registers a new user account with email, password, and personal information. Validates password strength and email uniqueness. Returns 409 if email already exists.", "request_body": { "schema_name": "UserCreate", "fields": [ { "name": "email", "type": "EmailStr", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "date_of_birth", "type": "date", "required": false, "nullable": true }, { "name": "gender", "type": "Gender", "required": false, "nullable": true, "enum_values": [ "MALE", "FEMALE", "OTHER", "PREFER_NOT_TO_SAY" ] }, { "name": "role", "type": "UserRole", "required": false, "enum_values": [ "ANONYMOUS", "REGISTERED_USER", "ADMINISTRATOR" ] }, { "name": "password", "type": "str", "required": true } ] }, "response": { "schema_name": "UserResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "date_of_birth", "type": "date", "required": false, "nullable": true }, { "name": "gender", "type": "Gender", "required": false, "nullable": true, "enum_values": [ "MALE", "FEMALE", "OTHER", "PREFER_NOT_TO_SAY" ] }, { "name": "is_active", "type": "bool", "required": true }, { "name": "role", "type": "UserRole", "required": true, "enum_values": [ "ANONYMOUS", "REGISTERED_USER", "ADMINISTRATOR" ] }, { "name": "last_login_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/{user_id}", "summary": "Get User by ID", "description": "Retrieves a single user record by ID. Returns 404 if user not found.", "path_params": [ { "name": "user_id", "type": "str" } ], "response": { "schema_name": "UserResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "date_of_birth", "type": "date", "required": false, "nullable": true }, { "name": "gender", "type": "Gender", "required": false, "nullable": true, "enum_values": [ "MALE", "FEMALE", "OTHER", "PREFER_NOT_TO_SAY" ] }, { "name": "is_active", "type": "bool", "required": true }, { "name": "role", "type": "UserRole", "required": true, "enum_values": [ "ANONYMOUS", "REGISTERED_USER", "ADMINISTRATOR" ] }, { "name": "last_login_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/", "summary": "List Users", "description": "Returns a paginated list of users. Supports optional filtering by active status and role.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "is_active", "type": "bool", "required": false }, { "name": "role", "type": "UserRole", "required": false } ], "response": { "schema_name": "UserResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "date_of_birth", "type": "date", "required": false, "nullable": true }, { "name": "gender", "type": "Gender", "required": false, "nullable": true, "enum_values": [ "MALE", "FEMALE", "OTHER", "PREFER_NOT_TO_SAY" ] }, { "name": "is_active", "type": "bool", "required": true }, { "name": "role", "type": "UserRole", "required": true, "enum_values": [ "ANONYMOUS", "REGISTERED_USER", "ADMINISTRATOR" ] }, { "name": "last_login_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/{user_id}", "summary": "Update User Account", "description": "Updates user account information. Validates email uniqueness if changed. Returns 404 if user not found, 409 if email conflict.", "path_params": [ { "name": "user_id", "type": "str" } ], "request_body": { "schema_name": "UserUpdate", "fields": [ { "name": "email", "type": "EmailStr", "required": false, "nullable": true }, { "name": "first_name", "type": "str", "required": false, "nullable": true }, { "name": "last_name", "type": "str", "required": false, "nullable": true }, { "name": "date_of_birth", "type": "date", "required": false, "nullable": true }, { "name": "gender", "type": "Gender", "required": false, "nullable": true, "enum_values": [ "MALE", "FEMALE", "OTHER", "PREFER_NOT_TO_SAY" ] }, { "name": "is_active", "type": "bool", "required": false, "nullable": true }, { "name": "role", "type": "UserRole", "required": false, "nullable": true, "enum_values": [ "ANONYMOUS", "REGISTERED_USER", "ADMINISTRATOR" ] }, { "name": "last_login_at", "type": "datetime", "required": false, "nullable": true } ] }, "response": { "schema_name": "UserResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "date_of_birth", "type": "date", "required": false, "nullable": true }, { "name": "gender", "type": "Gender", "required": false, "nullable": true, "enum_values": [ "MALE", "FEMALE", "OTHER", "PREFER_NOT_TO_SAY" ] }, { "name": "is_active", "type": "bool", "required": true }, { "name": "role", "type": "UserRole", "required": true, "enum_values": [ "ANONYMOUS", "REGISTERED_USER", "ADMINISTRATOR" ] }, { "name": "last_login_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{user_id}", "summary": "Delete User Account", "description": "Permanently deletes a user account and all associated data including profile, calculations, goals, and audit logs via cascade. Returns 404 if user not found.", "path_params": [ { "name": "user_id", "type": "str" } ], "status_code": 200 }, { "method": "GET", "path": "/{user_id}/details", "summary": "Get User Details with Profile", "description": "Retrieves user account information with associated profile data in a single response. Returns 404 if user not found.", "path_params": [ { "name": "user_id", "type": "str" } ], "response": { "schema_name": "UserDetailsResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "date_of_birth", "type": "date", "required": false, "nullable": true }, { "name": "gender", "type": "Gender", "required": false, "nullable": true, "enum_values": [ "MALE", "FEMALE", "OTHER", "PREFER_NOT_TO_SAY" ] }, { "name": "is_active", "type": "bool", "required": true }, { "name": "role", "type": "UserRole", "required": true, "enum_values": [ "ANONYMOUS", "REGISTERED_USER", "ADMINISTRATOR" ] }, { "name": "last_login_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "profile", "type": "ProfileResponse", "required": false, "nullable": true, "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "profile_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "preferred_unit", "type": "str", "required": true }, { "name": "target_bmi", "type": "float", "required": false, "nullable": true }, { "name": "target_weight", "type": "float", "required": false, "nullable": true }, { "name": "height_cm", "type": "float", "required": false, "nullable": true }, { "name": "current_weight_kg", "type": "float", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ] } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/{user_id}/disable", "summary": "Disable User Account", "description": "Deactivates a user account by setting is_active to false. Returns 404 if user not found, 400 if already disabled.", "path_params": [ { "name": "user_id", "type": "str" } ], "response": { "schema_name": "UserResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "date_of_birth", "type": "date", "required": false, "nullable": true }, { "name": "gender", "type": "Gender", "required": false, "nullable": true, "enum_values": [ "MALE", "FEMALE", "OTHER", "PREFER_NOT_TO_SAY" ] }, { "name": "is_active", "type": "bool", "required": true }, { "name": "role", "type": "UserRole", "required": true, "enum_values": [ "ANONYMOUS", "REGISTERED_USER", "ADMINISTRATOR" ] }, { "name": "last_login_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/{user_id}/enable", "summary": "Enable User Account", "description": "Reactivates a user account by setting is_active to true. Returns 404 if user not found, 400 if already enabled.", "path_params": [ { "name": "user_id", "type": "str" } ], "response": { "schema_name": "UserResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "date_of_birth", "type": "date", "required": false, "nullable": true }, { "name": "gender", "type": "Gender", "required": false, "nullable": true, "enum_values": [ "MALE", "FEMALE", "OTHER", "PREFER_NOT_TO_SAY" ] }, { "name": "is_active", "type": "bool", "required": true }, { "name": "role", "type": "UserRole", "required": true, "enum_values": [ "ANONYMOUS", "REGISTERED_USER", "ADMINISTRATOR" ] }, { "name": "last_login_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 } ] }, { "name": "BMI Calculation", "prefix": "/bmi", "endpoints": [ { "method": "POST", "path": "/categories", "summary": "Create BMI Category", "description": "Creates a new BMI category with min/max thresholds, description, and health recommendations. Returns 409 if a category with the same name already exists.", "request_body": { "schema_name": "BmicategoryCreate", "fields": [ { "name": "category_name", "type": "str", "required": false }, { "name": "min_bmi", "type": "float", "required": false }, { "name": "max_bmi", "type": "float", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "color_code", "type": "str", "required": false, "nullable": true }, { "name": "health_risk", "type": "str", "required": false, "nullable": true }, { "name": "recommendations", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "BmicategoryResponse", "fields": [ { "name": "category_name", "type": "str", "required": false }, { "name": "min_bmi", "type": "float", "required": false }, { "name": "max_bmi", "type": "float", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "color_code", "type": "str", "required": false, "nullable": true }, { "name": "health_risk", "type": "str", "required": false, "nullable": true }, { "name": "recommendations", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "category_id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/categories/{category_id}", "summary": "Get BMI Category", "description": "Retrieves a single BMI category by its ID. Returns 404 if the category does not exist.", "path_params": [ { "name": "category_id", "type": "str" } ], "response": { "schema_name": "BmicategoryResponse", "fields": [ { "name": "category_name", "type": "str", "required": false }, { "name": "min_bmi", "type": "float", "required": false }, { "name": "max_bmi", "type": "float", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "color_code", "type": "str", "required": false, "nullable": true }, { "name": "health_risk", "type": "str", "required": false, "nullable": true }, { "name": "recommendations", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "category_id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/categories", "summary": "List BMI Categories", "description": "Returns a paginated list of all BMI categories ordered by min_bmi ascending. Used for displaying category thresholds and health recommendations.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 } ], "response": { "schema_name": "BmicategoryResponse", "fields": [ { "name": "category_name", "type": "str", "required": false }, { "name": "min_bmi", "type": "float", "required": false }, { "name": "max_bmi", "type": "float", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "color_code", "type": "str", "required": false, "nullable": true }, { "name": "health_risk", "type": "str", "required": false, "nullable": true }, { "name": "recommendations", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "category_id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/categories/{category_id}", "summary": "Update BMI Category", "description": "Updates an existing BMI category. Validates that max_bmi is greater than min_bmi and that category_name remains unique. Returns 404 if category not found, 409 if name conflict.", "path_params": [ { "name": "category_id", "type": "str" } ], "request_body": { "schema_name": "BmicategoryUpdate", "fields": [ { "name": "category_name", "type": "str", "required": false, "nullable": true }, { "name": "min_bmi", "type": "float", "required": false, "nullable": true }, { "name": "max_bmi", "type": "float", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "color_code", "type": "str", "required": false, "nullable": true }, { "name": "health_risk", "type": "str", "required": false, "nullable": true }, { "name": "recommendations", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "BmicategoryResponse", "fields": [ { "name": "category_name", "type": "str", "required": false }, { "name": "min_bmi", "type": "float", "required": false }, { "name": "max_bmi", "type": "float", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "color_code", "type": "str", "required": false, "nullable": true }, { "name": "health_risk", "type": "str", "required": false, "nullable": true }, { "name": "recommendations", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "category_id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/categories/{category_id}", "summary": "Delete BMI Category", "description": "Permanently deletes a BMI category. Returns 404 if the category does not exist. May fail if calculations reference this category.", "path_params": [ { "name": "category_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/calculate", "summary": "Calculate BMI", "description": "Calculates BMI from height and weight, determines category, and optionally saves to history if user_id is provided. Anonymous calculations are not persisted. Updates user profile and goal progress when saved.", "request_body": { "schema_name": "BmiCalculationInput", "fields": [ { "name": "height_cm", "type": "float", "required": false }, { "name": "weight_kg", "type": "float", "required": false }, { "name": "unit", "type": "UnitSystem", "required": true, "enum_values": [ "METRIC", "IMPERIAL" ] }, { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "BmiCalculationResult", "fields": [ { "name": "bmi_value", "type": "float", "required": true }, { "name": "bmi_category", "type": "str", "required": true }, { "name": "category_id", "type": "str", "required": false, "nullable": true }, { "name": "height_cm", "type": "float", "required": true }, { "name": "weight_kg", "type": "float", "required": true }, { "name": "unit", "type": "str", "required": true }, { "name": "color_code", "type": "str", "required": false, "nullable": true }, { "name": "health_risk", "type": "str", "required": false, "nullable": true }, { "name": "recommendations", "type": "str", "required": false, "nullable": true }, { "name": "calculation_id", "type": "str", "required": false, "nullable": true }, { "name": "calculated_at", "type": "datetime", "required": false, "nullable": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/calculations", "summary": "Create BMI Calculation", "description": "Creates a new BMI calculation record with automatic BMI value and category determination. Updates user profile current weight and goal progress if user_id is provided. Returns 404 if user not found.", "request_body": { "schema_name": "BmicalculationCreate", "fields": [ { "name": "height_cm", "type": "float", "required": false }, { "name": "weight_kg", "type": "float", "required": false }, { "name": "unit", "type": "UnitSystem", "required": true, "enum_values": [ "METRIC", "IMPERIAL" ] }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "user_id", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "BmicalculationResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "calculation_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "height_cm", "type": "float", "required": true }, { "name": "weight_kg", "type": "float", "required": true }, { "name": "bmi_value", "type": "float", "required": true }, { "name": "bmi_category", "type": "str", "required": true }, { "name": "category_id", "type": "str", "required": false, "nullable": true }, { "name": "unit", "type": "str", "required": true }, { "name": "calculated_at", "type": "datetime", "required": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "is_deleted", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/calculations/{calculation_id}", "summary": "Get BMI Calculation", "description": "Retrieves a single BMI calculation by its ID. Returns 404 if the calculation does not exist.", "path_params": [ { "name": "calculation_id", "type": "str" } ], "response": { "schema_name": "BmicalculationResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "calculation_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "height_cm", "type": "float", "required": true }, { "name": "weight_kg", "type": "float", "required": true }, { "name": "bmi_value", "type": "float", "required": true }, { "name": "bmi_category", "type": "str", "required": true }, { "name": "category_id", "type": "str", "required": false, "nullable": true }, { "name": "unit", "type": "str", "required": true }, { "name": "calculated_at", "type": "datetime", "required": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "is_deleted", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/calculations/{calculation_id}/details", "summary": "Get BMI Calculation Details", "description": "Retrieves a BMI calculation with related user and category information including health risk and recommendations. Returns 404 if calculation not found.", "path_params": [ { "name": "calculation_id", "type": "str" } ], "response": { "schema_name": "BmicalculationDetailResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "calculation_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "height_cm", "type": "float", "required": true }, { "name": "weight_kg", "type": "float", "required": true }, { "name": "bmi_value", "type": "float", "required": true }, { "name": "bmi_category", "type": "str", "required": true }, { "name": "category_id", "type": "str", "required": false, "nullable": true }, { "name": "unit", "type": "str", "required": true }, { "name": "calculated_at", "type": "datetime", "required": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "is_deleted", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "user", "type": "UserBasicInfo", "required": false, "nullable": true, "fields": [ { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true } ] }, { "name": "category", "type": "BmicategoryDetailInfo", "required": false, "nullable": true, "fields": [ { "name": "category_name", "type": "str", "required": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "color_code", "type": "str", "required": false, "nullable": true }, { "name": "health_risk", "type": "str", "required": false, "nullable": true }, { "name": "recommendations", "type": "str", "required": false, "nullable": true } ] } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/calculations", "summary": "List BMI Calculations", "description": "Returns a paginated list of BMI calculations ordered by calculated_at descending. Supports filtering by user_id and is_deleted status.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "user_id", "type": "str", "required": false }, { "name": "is_deleted", "type": "bool", "required": false } ], "response": { "schema_name": "BmicalculationResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "calculation_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "height_cm", "type": "float", "required": true }, { "name": "weight_kg", "type": "float", "required": true }, { "name": "bmi_value", "type": "float", "required": true }, { "name": "bmi_category", "type": "str", "required": true }, { "name": "category_id", "type": "str", "required": false, "nullable": true }, { "name": "unit", "type": "str", "required": true }, { "name": "calculated_at", "type": "datetime", "required": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "is_deleted", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "PUT", "path": "/calculations/{calculation_id}", "summary": "Update BMI Calculation", "description": "Updates an existing BMI calculation. Recalculates BMI value and category if height or weight are changed. Returns 404 if calculation not found.", "path_params": [ { "name": "calculation_id", "type": "str" } ], "request_body": { "schema_name": "BmicalculationUpdate", "fields": [ { "name": "height_cm", "type": "float", "required": false, "nullable": true }, { "name": "weight_kg", "type": "float", "required": false, "nullable": true }, { "name": "unit", "type": "UnitSystem", "required": false, "nullable": true, "enum_values": [ "METRIC", "IMPERIAL" ] }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "is_deleted", "type": "bool", "required": false, "nullable": true } ] }, "response": { "schema_name": "BmicalculationResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "calculation_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "height_cm", "type": "float", "required": true }, { "name": "weight_kg", "type": "float", "required": true }, { "name": "bmi_value", "type": "float", "required": true }, { "name": "bmi_category", "type": "str", "required": true }, { "name": "category_id", "type": "str", "required": false, "nullable": true }, { "name": "unit", "type": "str", "required": true }, { "name": "calculated_at", "type": "datetime", "required": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "is_deleted", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/calculations/{calculation_id}", "summary": "Soft Delete BMI Calculation", "description": "Soft-deletes a BMI calculation by setting is_deleted to true. The record remains in the database but is excluded from history views. Returns 404 if calculation not found.", "path_params": [ { "name": "calculation_id", "type": "str" } ], "status_code": 200 } ] }, { "name": "Goals", "prefix": "/goals", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Goal", "description": "Creates a new goal for a user. Validates that the user exists, that they have fewer than 3 active goals, and that the target date is at least 7 days in the future and not more than 2 years away. Returns 400 if validation fails or 404 if the user does not exist.", "request_body": { "schema_name": "GoalCreate", "fields": [ { "name": "goal_type", "type": "str", "required": true }, { "name": "target_value", "type": "float", "required": true }, { "name": "current_value", "type": "float", "required": false, "nullable": true }, { "name": "start_date", "type": "date", "required": true }, { "name": "target_date", "type": "date", "required": true }, { "name": "status", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true } ] }, "response": { "schema_name": "GoalResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "goal_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "goal_type", "type": "str", "required": true }, { "name": "target_value", "type": "float", "required": true }, { "name": "current_value", "type": "float", "required": false, "nullable": true }, { "name": "start_date", "type": "date", "required": true }, { "name": "target_date", "type": "date", "required": true }, { "name": "status", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/", "summary": "List Goals", "description": "Returns a paginated list of goals. Supports optional filtering by user_id and status. Results are ordered by creation date descending.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "user_id", "type": "str", "required": false }, { "name": "status", "type": "GoalStatusEnum", "required": false } ], "response": { "schema_name": "GoalResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "goal_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "goal_type", "type": "str", "required": true }, { "name": "target_value", "type": "float", "required": true }, { "name": "current_value", "type": "float", "required": false, "nullable": true }, { "name": "start_date", "type": "date", "required": true }, { "name": "target_date", "type": "date", "required": true }, { "name": "status", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/{goal_id}", "summary": "Get Goal", "description": "Retrieves a single goal by its ID. Returns 404 if the goal does not exist.", "path_params": [ { "name": "goal_id", "type": "str" } ], "response": { "schema_name": "GoalResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "goal_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "goal_type", "type": "str", "required": true }, { "name": "target_value", "type": "float", "required": true }, { "name": "current_value", "type": "float", "required": false, "nullable": true }, { "name": "start_date", "type": "date", "required": true }, { "name": "target_date", "type": "date", "required": true }, { "name": "status", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{goal_id}/details", "summary": "Get Goal Details", "description": "Retrieves a goal with enriched details including the associated user's first and last name. Returns 404 if the goal does not exist.", "path_params": [ { "name": "goal_id", "type": "str" } ], "response": { "schema_name": "GoalDetailResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "goal_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "goal_type", "type": "str", "required": true }, { "name": "target_value", "type": "float", "required": true }, { "name": "current_value", "type": "float", "required": false, "nullable": true }, { "name": "start_date", "type": "date", "required": true }, { "name": "target_date", "type": "date", "required": true }, { "name": "status", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "user_first_name", "type": "str", "required": true }, { "name": "user_last_name", "type": "str", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/{goal_id}", "summary": "Update Goal", "description": "Updates an existing goal. All fields are optional. Validates target dates and target values according to business rules. Returns 404 if the goal does not exist or 400 if validation fails.", "path_params": [ { "name": "goal_id", "type": "str" } ], "request_body": { "schema_name": "GoalUpdate", "fields": [ { "name": "goal_type", "type": "str", "required": false, "nullable": true }, { "name": "target_value", "type": "float", "required": false, "nullable": true }, { "name": "current_value", "type": "float", "required": false, "nullable": true }, { "name": "start_date", "type": "date", "required": false, "nullable": true }, { "name": "target_date", "type": "date", "required": false, "nullable": true }, { "name": "status", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "GoalResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "goal_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "goal_type", "type": "str", "required": true }, { "name": "target_value", "type": "float", "required": true }, { "name": "current_value", "type": "float", "required": false, "nullable": true }, { "name": "start_date", "type": "date", "required": true }, { "name": "target_date", "type": "date", "required": true }, { "name": "status", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{goal_id}", "summary": "Delete Goal", "description": "Permanently deletes a goal by its ID. Returns 404 if the goal does not exist.", "path_params": [ { "name": "goal_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/{goal_id}/abandon", "summary": "Abandon Goal", "description": "Marks an active goal as abandoned. Returns 400 if the goal is not currently active or 404 if the goal does not exist.", "path_params": [ { "name": "goal_id", "type": "str" } ], "response": { "schema_name": "GoalResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "goal_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "goal_type", "type": "str", "required": true }, { "name": "target_value", "type": "float", "required": true }, { "name": "current_value", "type": "float", "required": false, "nullable": true }, { "name": "start_date", "type": "date", "required": true }, { "name": "target_date", "type": "date", "required": true }, { "name": "status", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/users/{user_id}/goals", "summary": "Get User Goals", "description": "Returns a paginated list of goals for a specific user. Supports optional filtering by status. Returns 404 if the user does not exist.", "path_params": [ { "name": "user_id", "type": "str" } ], "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "status", "type": "GoalStatusEnum", "required": false } ], "response": { "schema_name": "GoalResponse", "fields": [ { "name": "id", "type": "str", "required": true }, { "name": "goal_id", "type": "str", "required": true }, { "name": "user_id", "type": "str", "required": true }, { "name": "goal_type", "type": "str", "required": true }, { "name": "target_value", "type": "float", "required": true }, { "name": "current_value", "type": "float", "required": false, "nullable": true }, { "name": "start_date", "type": "date", "required": true }, { "name": "target_date", "type": "date", "required": true }, { "name": "status", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 } ] }, { "name": "Audit Logs", "prefix": "/audit-logs", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Audit Log", "description": "Creates a new audit log entry recording a system action or user activity. Validates that the user_id exists if provided. Returns the created audit log with generated ID and timestamps.", "request_body": { "schema_name": "AuditlogCreate", "fields": [ { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "action", "type": "str", "required": true }, { "name": "entity_type", "type": "str", "required": false, "nullable": true }, { "name": "entity_id", "type": "str", "required": false, "nullable": true }, { "name": "timestamp", "type": "datetime", "required": true }, { "name": "ip_address", "type": "str", "required": false, "nullable": true }, { "name": "user_agent", "type": "str", "required": false, "nullable": true }, { "name": "details", "type": "dict", "required": false, "nullable": true } ] }, "response": { "schema_name": "AuditlogResponse", "fields": [ { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "action", "type": "str", "required": true }, { "name": "entity_type", "type": "str", "required": false, "nullable": true }, { "name": "entity_id", "type": "str", "required": false, "nullable": true }, { "name": "timestamp", "type": "datetime", "required": true }, { "name": "ip_address", "type": "str", "required": false, "nullable": true }, { "name": "user_agent", "type": "str", "required": false, "nullable": true }, { "name": "details", "type": "dict", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "log_id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/", "summary": "List Audit Logs", "description": "Returns a paginated list of audit logs ordered by timestamp descending. Supports optional filtering by user_id, action, entity_type, and entity_id to narrow down results.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "user_id", "type": "str", "required": false }, { "name": "action", "type": "str", "required": false }, { "name": "entity_type", "type": "str", "required": false }, { "name": "entity_id", "type": "str", "required": false } ], "response": { "schema_name": "AuditlogResponse", "fields": [ { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "action", "type": "str", "required": true }, { "name": "entity_type", "type": "str", "required": false, "nullable": true }, { "name": "entity_id", "type": "str", "required": false, "nullable": true }, { "name": "timestamp", "type": "datetime", "required": true }, { "name": "ip_address", "type": "str", "required": false, "nullable": true }, { "name": "user_agent", "type": "str", "required": false, "nullable": true }, { "name": "details", "type": "dict", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "log_id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/{auditlog_id}", "summary": "Get Audit Log", "description": "Retrieves a single audit log entry by its unique ID. Returns 404 if the audit log does not exist.", "path_params": [ { "name": "auditlog_id", "type": "str" } ], "response": { "schema_name": "AuditlogResponse", "fields": [ { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "action", "type": "str", "required": true }, { "name": "entity_type", "type": "str", "required": false, "nullable": true }, { "name": "entity_id", "type": "str", "required": false, "nullable": true }, { "name": "timestamp", "type": "datetime", "required": true }, { "name": "ip_address", "type": "str", "required": false, "nullable": true }, { "name": "user_agent", "type": "str", "required": false, "nullable": true }, { "name": "details", "type": "dict", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "log_id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{auditlog_id}/details", "summary": "Get Audit Log Details", "description": "Retrieves a single audit log entry with enriched details including the associated user's first and last name. Returns 404 if the audit log does not exist.", "path_params": [ { "name": "auditlog_id", "type": "str" } ], "response": { "schema_name": "AuditlogDetailResponse", "fields": [ { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "action", "type": "str", "required": true }, { "name": "entity_type", "type": "str", "required": false, "nullable": true }, { "name": "entity_id", "type": "str", "required": false, "nullable": true }, { "name": "timestamp", "type": "datetime", "required": true }, { "name": "ip_address", "type": "str", "required": false, "nullable": true }, { "name": "user_agent", "type": "str", "required": false, "nullable": true }, { "name": "details", "type": "dict", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "log_id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "user_first_name", "type": "str", "required": false, "nullable": true }, { "name": "user_last_name", "type": "str", "required": false, "nullable": true } ], "is_list": false }, "status_code": 200 }, { "method": "PATCH", "path": "/{auditlog_id}", "summary": "Update Audit Log", "description": "Updates an existing audit log entry with partial data. Only provided fields are modified. Validates that user_id exists if changed. Returns 404 if the audit log does not exist.", "path_params": [ { "name": "auditlog_id", "type": "str" } ], "request_body": { "schema_name": "AuditlogUpdate", "fields": [ { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "action", "type": "str", "required": false, "nullable": true }, { "name": "entity_type", "type": "str", "required": false, "nullable": true }, { "name": "entity_id", "type": "str", "required": false, "nullable": true }, { "name": "timestamp", "type": "datetime", "required": false, "nullable": true }, { "name": "ip_address", "type": "str", "required": false, "nullable": true }, { "name": "user_agent", "type": "str", "required": false, "nullable": true }, { "name": "details", "type": "dict", "required": false, "nullable": true } ] }, "response": { "schema_name": "AuditlogResponse", "fields": [ { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "action", "type": "str", "required": true }, { "name": "entity_type", "type": "str", "required": false, "nullable": true }, { "name": "entity_id", "type": "str", "required": false, "nullable": true }, { "name": "timestamp", "type": "datetime", "required": true }, { "name": "ip_address", "type": "str", "required": false, "nullable": true }, { "name": "user_agent", "type": "str", "required": false, "nullable": true }, { "name": "details", "type": "dict", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "log_id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{auditlog_id}", "summary": "Delete Audit Log", "description": "Permanently deletes an audit log entry by its unique ID. Returns 404 if the audit log does not exist. Note: audit logs are typically retained for compliance; deletion should be restricted.", "path_params": [ { "name": "auditlog_id", "type": "str" } ], "status_code": 200 }, { "method": "GET", "path": "/users/{user_id}/logs", "summary": "List User Audit Logs", "description": "Returns a paginated list of all audit logs for a specific user, ordered by timestamp descending. Returns 404 if the user does not exist.", "path_params": [ { "name": "user_id", "type": "str" } ], "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 } ], "response": { "schema_name": "AuditlogResponse", "fields": [ { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "action", "type": "str", "required": true }, { "name": "entity_type", "type": "str", "required": false, "nullable": true }, { "name": "entity_id", "type": "str", "required": false, "nullable": true }, { "name": "timestamp", "type": "datetime", "required": true }, { "name": "ip_address", "type": "str", "required": false, "nullable": true }, { "name": "user_agent", "type": "str", "required": false, "nullable": true }, { "name": "details", "type": "dict", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "log_id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 }, { "method": "GET", "path": "/entities/{entity_type}/{entity_id}/logs", "summary": "List Entity Audit Logs", "description": "Returns a paginated list of all audit logs for a specific entity identified by type and ID, ordered by timestamp descending. Useful for tracking all actions performed on a particular record.", "path_params": [ { "name": "entity_type", "type": "str" }, { "name": "entity_id", "type": "str" } ], "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 } ], "response": { "schema_name": "AuditlogResponse", "fields": [ { "name": "user_id", "type": "str", "required": false, "nullable": true }, { "name": "action", "type": "str", "required": true }, { "name": "entity_type", "type": "str", "required": false, "nullable": true }, { "name": "entity_id", "type": "str", "required": false, "nullable": true }, { "name": "timestamp", "type": "datetime", "required": true }, { "name": "ip_address", "type": "str", "required": false, "nullable": true }, { "name": "user_agent", "type": "str", "required": false, "nullable": true }, { "name": "details", "type": "dict", "required": false, "nullable": true }, { "name": "id", "type": "str", "required": true }, { "name": "log_id", "type": "str", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": true }, "status_code": 200 } ] } ], "enums": { "Gender": [ "MALE", "FEMALE", "OTHER", "PREFER_NOT_TO_SAY" ], "UserRole": [ "ANONYMOUS", "REGISTERED_USER", "ADMINISTRATOR" ], "UnitSystem": [ "METRIC", "IMPERIAL" ], "GoalTypeEnum": [ "BMI", "WEIGHT" ], "GoalStatusEnum": [ "ACTIVE", "ACHIEVED", "ABANDONED" ] } }