CBT API Docs

Backend Specifications

CBT App - Backend API Documentation

Comprehensive API specifications for Flutter CBT Application

🛠️ Required Technology Stack

Backend Framework: Go with Fiber framework

API Documentation: Swagger (use fiber-swagger for automatic documentation)

Architecture: Microservices (separate services for different functionalities)

Database: Your choice (PostgreSQL/MongoDB recommended)

🔐 1. Authentication Service

Service Overview

Handles user registration, login, password reset, and JWT token management.

POST /api/auth/register

Description

Register a new user account

Request Body

{
  "full_name": "David Johnson",
  "email": "david.johnson@email.com",
  "password": "SecurePassword123!"
}

Request Fields

Field Type Required Description
full_name string Yes User's full name (min: 2, max: 100 chars)
email string Yes Valid email address (unique)
password string Yes Password (min: 8 chars)

Success Response (201)

{
  "success": true,
  "message": "Account created successfully",
  "data": {
    "user_id": "uuid-string",
    "full_name": "David Johnson",
    "email": "david.johnson@email.com",
    "account_status": "none",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "token": {
    "access_token": "jwt-token-string",
    "refresh_token": "refresh-token-string",
    "expires_in": 3600
  }
}

Error Response (400/409)

{
  "success": false,
  "message": "Email already exists",
  "errors": [
    {
      "field": "email",
      "message": "This email is already registered"
    }
  ]
}
POST /api/auth/login

Description

Authenticate user and return access tokens

Request Body

{
  "email": "david.johnson@email.com",
  "password": "SecurePassword123!"
}

Success Response (200)

{
  "success": true,
  "message": "Login successful",
  "data": {
    "user_id": "uuid-string",
    "full_name": "David Johnson",
    "email": "david.johnson@email.com",
    "account_status": "none",
    "profile_completed": false,
    "last_login": "2024-01-15T10:30:00Z"
  },
  "token": {
    "access_token": "jwt-token-string",
    "refresh_token": "refresh-token-string",
    "expires_in": 3600
  }
}

Error Response (401)

{
  "success": false,
  "message": "Invalid credentials",
  "errors": [
    {
      "field": "credentials",
      "message": "Email or password is incorrect"
    }
  ]
}
POST /api/auth/forgot-password

Description

Send password reset link to user's email

Request Body

{
  "email": "david.johnson@email.com"
}

Success Response (200)

{
  "success": true,
  "message": "Password reset link sent to your email",
  "data": {
    "email": "david.johnson@email.com",
    "reset_token_expires": "2024-01-15T11:30:00Z"
  }
}
POST /api/auth/reset-password

Description

Reset user password using reset token

Request Body

{
  "reset_token": "reset-token-string",
  "new_password": "NewSecurePassword123!"
}

Success Response (200)

{
  "success": true,
  "message": "Password reset successfully",
  "data": {
    "user_id": "uuid-string",
    "password_changed_at": "2024-01-15T10:30:00Z"
  }
}

👨‍💼 2. Admin Authentication Service

Service Overview

Separate authentication system for admin users with enhanced security and different endpoints.

POST /api/admin/auth/register

Description

Register a new admin account (requires super admin approval)

Request Body

{
  "full_name": "Admin User",
  "email": "admin@cbtapp.com",
  "password": "AdminSecurePassword123!",
  "admin_code": "ADMIN_REGISTRATION_CODE_2024",
  "department": "System Administration",
  "phone": "+234801234567"
}

Request Fields

Field Type Required Description
full_name string Yes Admin's full name
email string Yes Admin email address (unique)
password string Yes Strong password (min: 12 chars)
admin_code string Yes Special registration code for admins
department string Yes Admin department/role
phone string Yes Admin phone number

Success Response (201)

{
  "success": true,
  "message": "Admin account created successfully. Awaiting approval.",
  "data": {
    "admin_id": "admin-uuid-string",
    "full_name": "Admin User",
    "email": "admin@cbtapp.com",
    "department": "System Administration",
    "status": "pending_approval",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Error Response (400/403)

{
  "success": false,
  "message": "Invalid admin registration code",
  "errors": [
    {
      "field": "admin_code",
      "message": "The provided admin code is invalid or expired"
    }
  ]
}
POST /api/admin/auth/login

Description

Authenticate admin user and return admin access tokens

Request Body

{
  "email": "admin@cbtapp.com",
  "password": "AdminSecurePassword123!",
  "two_factor_code": "123456"
}

Request Fields

Field Type Required Description
email string Yes Admin email address
password string Yes Admin password
two_factor_code string No 2FA code (if enabled)

Success Response (200)

{
  "success": true,
  "message": "Admin login successful",
  "data": {
    "admin_id": "admin-uuid-string",
    "full_name": "Admin User",
    "email": "admin@cbtapp.com",
    "department": "System Administration",
    "role": "admin",
    "permissions": [
      "manage_users",
      "manage_vouchers",
      "view_analytics",
      "system_settings"
    ],
    "last_login": "2024-01-15T10:30:00Z",
    "status": "active"
  },
  "token": {
    "access_token": "admin-jwt-token-string",
    "refresh_token": "admin-refresh-token-string",
    "expires_in": 7200,
    "token_type": "admin"
  }
}

Error Response (401/403)

{
  "success": false,
  "message": "Admin account not approved",
  "errors": [
    {
      "field": "account_status",
      "message": "Your admin account is pending approval. Contact super admin."
    }
  ]
}
POST /api/admin/auth/forgot-password

Description

Send password reset link to admin's email

Request Body

{
  "email": "admin@cbtapp.com",
  "admin_code": "ADMIN_RESET_CODE_2024"
}

Success Response (200)

{
  "success": true,
  "message": "Admin password reset link sent to your email",
  "data": {
    "email": "admin@cbtapp.com",
    "reset_token_expires": "2024-01-15T11:30:00Z"
  }
}
POST /api/admin/auth/logout

Description

Logout admin user and invalidate tokens

Headers

Authorization: Bearer {admin_access_token}

Success Response (200)

{
  "success": true,
  "message": "Admin logged out successfully",
  "data": {
    "admin_id": "admin-uuid-string",
    "logged_out_at": "2024-01-15T10:30:00Z"
  }
}

👤 3. Profile Management Service

Service Overview

Manages user profile information including personal details, location, and education information.

GET /api/profile

Description

Get current user's profile information

Headers

Authorization: Bearer {access_token}

Success Response (200)

{
  "success": true,
  "data": {
    "user_id": "uuid-string",
    "full_name": "David Johnson",
    "email": "david.johnson@email.com",
    "age": 20,
    "phone": "+234801234567",
    "date_of_birth": "2004-01-15",
    "country": "Nigeria",
    "state": "Lagos",
    "school": "University of Lagos",
    "profile_completed": true,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}
PUT /api/profile

Description

Update user profile information

Headers

Authorization: Bearer {access_token}

Request Body

{
  "age": 20,
  "phone": "+234801234567",
  "date_of_birth": "2004-01-15",
  "country": "Nigeria",
  "state": "Lagos",
  "school": "University of Lagos"
}

Request Fields

Field Type Required Description
age integer Yes User's age (10-100)
phone string Yes Phone number with country code
date_of_birth string Yes Date in YYYY-MM-DD format
country string Yes Country name
state string Yes State/Province name
school string Yes School/University name

Success Response (200)

{
  "success": true,
  "message": "Profile updated successfully",
  "data": {
    "user_id": "uuid-string",
    "profile_completed": true,
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

📋 4. Disclaimer Service

Service Overview

Manages user agreement to disclaimer terms and conditions.

POST /api/disclaimer/accept

Description

Record user's acceptance of disclaimer terms

Headers

Authorization: Bearer {access_token}

Request Body

{
  "agreed": true,
  "disclaimer_version": "1.0",
  "ip_address": "192.168.1.1"
}

Success Response (200)

{
  "success": true,
  "message": "Disclaimer accepted successfully",
  "data": {
    "user_id": "uuid-string",
    "agreed": true,
    "disclaimer_version": "1.0",
    "accepted_at": "2024-01-15T10:30:00Z"
  }
}
GET /api/disclaimer/status

Description

Check if user has accepted the current disclaimer

Headers

Authorization: Bearer {access_token}

Success Response (200)

{
  "success": true,
  "data": {
    "user_id": "uuid-string",
    "has_agreed": true,
    "disclaimer_version": "1.0",
    "accepted_at": "2024-01-15T10:30:00Z",
    "current_version": "1.0",
    "needs_update": false
  }
}

📚 5. Exam Management Service

Service Overview

Manages exam bodies, subjects, and user exam selections.

GET /api/exams/bodies

Description

Get list of available exam bodies

Success Response (200)

{
  "success": true,
  "data": {
    "nigerian_exams": [
      {
        "id": "jamb",
        "name": "JAMB",
        "description": "Joint Admissions and Matriculation Board",
        "max_subjects": 4,
        "required_subjects": ["English Language", "Mathematics"]
      },
      {
        "id": "waec",
        "name": "WAEC",
        "description": "West African Examinations Council",
        "max_subjects": 9,
        "required_subjects": ["English Language", "Mathematics"]
      },
      {
        "id": "neco",
        "name": "NECO",
        "description": "National Examinations Council",
        "max_subjects": 9,
        "required_subjects": ["English Language", "Mathematics"]
      },
      {
        "id": "post-utme",
        "name": "Post-UTME",
        "description": "Post Unified Tertiary Matriculation Exam",
        "max_subjects": 4,
        "required_subjects": ["English Language", "Mathematics"]
      }
    ],
    "international_exams": [
      {
        "id": "ielts",
        "name": "IELTS",
        "description": "International English Language Testing",
        "sections": ["Listening", "Reading", "Writing", "Speaking"]
      },
      {
        "id": "toefl",
        "name": "TOEFL",
        "description": "Test of English as a Foreign Language",
        "sections": ["Reading", "Listening", "Speaking", "Writing"]
      }
    ]
  }
}
GET /api/exams/{exam_body_id}/subjects

Description

Get available subjects for a specific exam body

Path Parameters

Parameter Type Description
exam_body_id string Exam body identifier (jamb, waec, neco, etc.)

Success Response (200)

{
  "success": true,
  "data": {
    "exam_body": "jamb",
    "categories": {
      "core_subjects": [
        {
          "id": "english",
          "name": "English Language",
          "required": true,
          "category": "core"
        },
        {
          "id": "mathematics",
          "name": "Mathematics",
          "required": true,
          "category": "core"
        }
      ],
      "science_subjects": [
        {
          "id": "physics",
          "name": "Physics",
          "required": false,
          "category": "science"
        },
        {
          "id": "chemistry",
          "name": "Chemistry",
          "required": false,
          "category": "science"
        },
        {
          "id": "biology",
          "name": "Biology",
          "required": false,
          "category": "science"
        }
      ],
      "arts_subjects": [
        {
          "id": "literature",
          "name": "Literature in English",
          "required": false,
          "category": "arts"
        },
        {
          "id": "government",
          "name": "Government",
          "required": false,
          "category": "arts"
        }
      ]
    }
  }
}
POST /api/exams/user-selection

Description

Save user's exam body and subject selections

Headers

Authorization: Bearer {access_token}

Request Body

{
  "exam_body": "jamb",
  "selected_subjects": [
    "english",
    "mathematics",
    "physics",
    "chemistry"
  ]
}

Success Response (201)

{
  "success": true,
  "message": "Exam selection saved successfully",
  "data": {
    "user_id": "uuid-string",
    "exam_body": "jamb",
    "selected_subjects": [
      "english",
      "mathematics", 
      "physics",
      "chemistry"
    ],
    "created_at": "2024-01-15T10:30:00Z"
  }
}
GET /api/exams/user-selection

Description

Get user's current exam selections

Headers

Authorization: Bearer {access_token}

Success Response (200)

{
  "success": true,
  "data": {
    "user_id": "uuid-string",
    "exam_body": "jamb",
    "selected_subjects": [
      {
        "id": "english",
        "name": "English Language",
        "category": "core"
      },
      {
        "id": "mathematics",
        "name": "Mathematics",
        "category": "core"
      },
      {
        "id": "physics",
        "name": "Physics",
        "category": "science"
      },
      {
        "id": "chemistry",
        "name": "Chemistry",
        "category": "science"
      }
    ],
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

🎯 6. Subject Weakness Service

Service Overview

Manages user's identified weak areas and improvement goals for personalized learning.

POST /api/weaknesses

Description

Save user's identified weak areas and improvement goals

Headers

Authorization: Bearer {access_token}

Request Body

{
  "subject": "mathematics",
  "weak_areas": [
    "Linear equations",
    "Quadratic equations",
    "Differentiation"
  ],
  "improvement_goals": [
    "Speed and Accuracy",
    "Problem-solving techniques",
    "Time management"
  ]
}

Request Fields

Field Type Required Description
subject string Yes Subject identifier
weak_areas array No List of specific topics user finds challenging
improvement_goals array No List of skills user wants to improve

Success Response (201)

{
  "success": true,
  "message": "Weakness assessment saved successfully",
  "data": {
    "user_id": "uuid-string",
    "subject": "mathematics",
    "weak_areas": [
      "Linear equations",
      "Quadratic equations",
      "Differentiation"
    ],
    "improvement_goals": [
      "Speed and Accuracy",
      "Problem-solving techniques",
      "Time management"
    ],
    "created_at": "2024-01-15T10:30:00Z"
  }
}
GET /api/weaknesses

Description

Get user's weakness assessments for all subjects

Headers

Authorization: Bearer {access_token}

Success Response (200)

{
  "success": true,
  "data": [
    {
      "subject": "mathematics",
      "weak_areas": [
        "Linear equations",
        "Quadratic equations"
      ],
      "improvement_goals": [
        "Speed and Accuracy",
        "Problem-solving techniques"
      ],
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    {
      "subject": "physics",
      "weak_areas": [
        "Motion",
        "Forces"
      ],
      "improvement_goals": [
        "Understanding concepts",
        "Application of knowledge"
      ],
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ]
}
GET /api/subjects/{subject_id}/topics

Description

Get available topics for a specific subject

Path Parameters

Parameter Type Description
subject_id string Subject identifier (mathematics, physics, etc.)

Success Response (200)

{
  "success": true,
  "data": {
    "subject": "mathematics",
    "categories": {
      "Algebra": [
        "Linear equations",
        "Quadratic equations",
        "Polynomials",
        "Factorization"
      ],
      "Geometry": [
        "Angles",
        "Triangles",
        "Circles",
        "Area and Perimeter"
      ],
      "Calculus": [
        "Differentiation",
        "Integration",
        "Limits",
        "Applications"
      ]
    }
  }
}

⭐ 7. Account Status Service

Service Overview

Manages user account status including trial periods, premium subscriptions, and access control.

Account Status Types (Enum)
none: New user with no active subscription or trial
trial: User with active 11-day free trial
voucher: User with active voucher-based subscription
GET /api/account/status

Description

Get current user's account status and subscription details

Headers

Authorization: Bearer {access_token}

Success Response (200)

{
  "success": true,
  "data": {
    "user_id": "uuid-string",
    "account_status": "trial",
    "subscription_type": "trial",
    "is_active": true,
    "trial_started_at": "2024-01-15T10:30:00Z",
    "expires_at": "2024-01-26T10:30:00Z",
    "days_remaining": 11,
    "features_access": {
      "practice_questions": true,
      "progress_tracking": true,
      "unlimited_access": false
    },
    "usage_limits": {
      "daily_questions": 50,
      "questions_used_today": 15
    }
  }
}
POST /api/account/start-trial

Description

Start 11-day free trial for user

Headers

Authorization: Bearer {access_token}

Request Body

{
  "exam_type": "jamb",
  "selected_subjects": [
    "english",
    "mathematics",
    "physics",
    "chemistry"
  ]
}

Success Response (201)

{
  "success": true,
  "message": "Trial started successfully",
  "data": {
    "user_id": "uuid-string",
    "account_status": "trial",
    "trial_started_at": "2024-01-15T10:30:00Z",
    "expires_at": "2024-01-26T10:30:00Z",
    "trial_duration_days": 11,
    "exam_type": "jamb",
    "selected_subjects": [
      "english",
      "mathematics",
      "physics",
      "chemistry"
    ]
  }
}

Error Response (400)

{
  "success": false,
  "message": "Trial already used",
  "errors": [
    {
      "field": "trial",
      "message": "User has already used their free trial"
    }
  ]
}
GET /api/account/trial-status

Description

Check if user's trial is still valid

Headers

Authorization: Bearer {access_token}

Success Response (200)

{
  "success": true,
  "data": {
    "user_id": "uuid-string",
    "has_trial": true,
    "trial_active": true,
    "trial_expired": false,
    "started_at": "2024-01-15T10:30:00Z",
    "expires_at": "2024-01-26T10:30:00Z",
    "days_remaining": 8,
    "hours_remaining": 192
  }
}
POST /api/account/upgrade

Description

Upgrade account to premium (used after voucher activation)

Headers

Authorization: Bearer {access_token}

Request Body

{
  "subscription_type": "premium",
  "duration_months": 6,
  "voucher_code": "ABCD1234EFGH5678",
  "payment_method": "voucher"
}

Success Response (200)

{
  "success": true,
  "message": "Account upgraded successfully",
  "data": {
    "user_id": "uuid-string",
    "account_status": "voucher",
    "subscription_type": "premium",
    "activated_at": "2024-01-15T10:30:00Z",
    "expires_at": "2024-07-15T10:30:00Z",
    "duration_months": 6,
    "features_access": {
      "practice_questions": true,
      "progress_tracking": true,
      "unlimited_access": true,
      "detailed_analytics": true
    }
  }
}

🎫 8. Voucher Service

Service Overview

Manages voucher codes for account activation and premium subscriptions.

POST /api/vouchers/validate

Description

Validate voucher code before activation

Headers

Authorization: Bearer {access_token}

Request Body

{
  "voucher_code": "ABCD1234EFGH5678"
}

Success Response (200)

{
  "success": true,
  "message": "Voucher is valid",
  "data": {
    "voucher_code": "ABCD1234EFGH5678",
    "is_valid": true,
    "is_used": false,
    "subscription_type": "premium",
    "duration_months": 6,
    "value": "₦1,000",
    "expires_at": "2025-12-31T23:59:59Z"
  }
}

Error Response (400)

{
  "success": false,
  "message": "Invalid voucher code",
  "errors": [
    {
      "field": "voucher_code",
      "message": "Voucher code is invalid or has already been used"
    }
  ]
}
POST /api/vouchers/activate

Description

Activate voucher code and upgrade user account

Headers

Authorization: Bearer {access_token}

Request Body

{
  "voucher_code": "ABCD1234EFGH5678"
}

Success Response (200)

{
  "success": true,
  "message": "Voucher activated successfully",
  "data": {
    "user_id": "uuid-string",
    "voucher_code": "ABCD1234EFGH5678",
    "activated_at": "2024-01-15T10:30:00Z",
    "subscription_type": "premium",
    "duration_months": 6,
    "account_expires_at": "2024-07-15T10:30:00Z",
    "previous_status": "trial",
    "new_status": "voucher"
  }
}
GET /api/vouchers/history

Description

Get user's voucher activation history

Headers

Authorization: Bearer {access_token}

Success Response (200)

{
  "success": true,
  "data": [
    {
      "voucher_code": "ABCD1234EFGH5678",
      "activated_at": "2024-01-15T10:30:00Z",
      "subscription_type": "premium",
      "duration_months": 6,
      "value": "₦1,000",
      "status": "active"
    }
  ]
}

👥 9. User Role Service

Service Overview

Manages different user roles: students and agents (voucher resellers).

GET /api/users/role

Description

Get current user's role and permissions

Headers

Authorization: Bearer {access_token}

Success Response (200)

{
  "success": true,
  "data": {
    "user_id": "uuid-string",
    "role": "student",
    "role_details": {
      "name": "Student",
      "description": "Regular student account",
      "permissions": [
        "access_practice",
        "view_progress",
        "use_vouchers"
      ]
    },
    "assigned_at": "2024-01-15T10:30:00Z"
  }
}
PUT /api/users/role

Description

Update user role (admin only)

Headers

Authorization: Bearer {admin_access_token}

Request Body

{
  "user_id": "target-user-uuid",
  "new_role": "agent",
  "reason": "User approved as voucher reseller"
}

Request Fields

Field Type Required Description
user_id string Yes Target user's UUID
new_role string Yes New role: student, agent, admin
reason string No Reason for role change

Success Response (200)

{
  "success": true,
  "message": "User role updated successfully",
  "data": {
    "user_id": "target-user-uuid",
    "previous_role": "student",
    "new_role": "agent",
    "updated_by": "admin-user-uuid",
    "updated_at": "2024-01-15T10:30:00Z",
    "reason": "User approved as voucher reseller"
  }
}
GET /api/roles

Description

Get all available roles and their permissions

Success Response (200)

{
  "success": true,
  "data": {
    "roles": [
      {
        "id": "student",
        "name": "Student",
        "description": "Regular student account",
        "permissions": [
          "access_practice",
          "view_progress",
          "use_vouchers",
          "update_profile"
        ]
      },
      {
        "id": "agent",
        "name": "Agent",
        "description": "Voucher reseller account",
        "permissions": [
          "access_practice",
          "view_progress",
          "use_vouchers",
          "update_profile",
          "sell_vouchers",
          "view_sales_dashboard",
          "generate_voucher_reports"
        ]
      },
      {
        "id": "admin",
        "name": "Administrator",
        "description": "System administrator",
        "permissions": [
          "*"
        ]
      }
    ]
  }
}
POST /api/users/role-application

Description

Apply for role change (student to agent)

Headers

Authorization: Bearer {access_token}

Request Body

{
  "requested_role": "agent",
  "business_name": "EduTech Solutions",
  "business_address": "123 Education Street, Lagos",
  "phone_number": "+234801234567",
  "reason": "I want to help students in my community access quality education",
  "experience": "5 years in educational services",
  "documents": [
    {
      "type": "business_registration",
      "url": "https://example.com/documents/business_reg.pdf"
    },
    {
      "type": "identification",
      "url": "https://example.com/documents/id_card.pdf"
    }
  ]
}

Success Response (201)

{
  "success": true,
  "message": "Role application submitted successfully",
  "data": {
    "application_id": "app-uuid-string",
    "user_id": "uuid-string",
    "requested_role": "agent",
    "status": "pending",
    "submitted_at": "2024-01-15T10:30:00Z",
    "estimated_review_time": "3-5 business days"
  }
}

🚀 Implementation Notes

Swagger Documentation: Use fiber-swagger to automatically generate interactive API documentation at /swagger/index.html

Authentication: All protected endpoints require JWT Bearer token in Authorization header

Admin Authentication: Separate admin endpoints with enhanced security and different token validation

Account Status Enum: Use the three account status types (none, trial, voucher) for easy access control

Error Handling: Return consistent error responses with appropriate HTTP status codes

Database: Design normalized database schema with proper relationships and indexes

Validation: Implement server-side validation for all input data

Security: Implement rate limiting, input sanitization, and CORS policies

Logging: Add comprehensive logging for debugging and monitoring