API Docs - SillyRobot883/inma-frontend GitHub Wiki

Inma Clubs Management System API Documentation

Overview

REST API documentation for the Inma Clubs Management System. The API uses JSON for request/response bodies and JWT for authentication.

Base URL

.../v1

Authentication

All API requests require authentication using JWT Bearer token:

Authorization: Bearer <token>

Common Parameters

Pagination

  • page: Page number (default: 1)
  • limit: Items per page (default: 10, max: 50)

Filtering & Sorting

  • sort: Sort field (e.g., sort=name or sort=-createdAt for descending)
  • fields: Comma-separated list of fields to return
  • include: Related data to include

Response Format

{
  "status": "success",
  "data": {},
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 100
  }
}

Error Responses

{
  "status": "error",
  "error": {
    "code": "ERROR_CODE",
    "message": "Error description"
  }
}

HTTP Status Codes

Success Codes

  • 200 OK: Request successful (GET, PATCH)
  • 201 Created: Resource created successfully (POST)
  • 204 No Content: Request successful, no content returned (DELETE)

Client Error Codes

  • 400 Bad Request: Invalid request parameters or validation failed
  • 401 Unauthorized: Missing or invalid authentication token
  • 403 Forbidden: Valid token but insufficient permissions
  • 404 Not Found: Requested resource doesn't exist
  • 429 Too Many Requests: Rate limit exceeded

Server Error Codes

  • 500 Internal Server Error: Unexpected server error

Examples:

200: GET /clubs successful
201: POST /volunteer-hours successful
400: Invalid hours format in submission
401: Missing JWT token
403: Non-admin trying to approve hours
404: Club ID not found
429: Too many requests to /clubs endpoint

Endpoints

Authentication

POST /auth/login

Login user and get access token.

Request:

{
  "email": "string",
  "password": "string"
}

Response:

{
  "status": "success",
  "data": {
    "accessToken": "string",
    "refreshToken": "string",
    "user": {
      "id": "string",
      "name": "string",
      "role": "string",
      "clubs": [
        {
          "id": "string",
          "name": "string",
          "role": "string"
        }
      ]
    }
  }
}

POST /auth/refresh

Refresh access token.

POST /auth/logout

Invalidate current tokens.

Clubs

GET /clubs

Get list of clubs.

Query Parameters:

  • fields: Select specific fields (e.g., fields=id,name,totalMembers)
  • include: Include related data (e.g., include=stats,members)
  • search: Search term for club name
  • college: Filter by college
  • status: Filter by status (active/inactive)

Response:

{
  "status": "success",
  "data": {
    "clubs": [
      {
        "id": "string",
        "name": "string",
        "members": {
          "total": "number",
          "active": "number"
        },
        "stats": {
          "totalHours": "number",
          "pendingTasks": "number",
          "completedTasks": "number"
        }
      }
    ]
  },
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 100
  }
}

GET /clubs/:clubId

Get detailed club information.

Query Parameters:

  • include: Include related data (achievements,events,topPerformers,recentActivity)

Response:

{
  "status": "success",
  "data": {
    "club": {
      "id": "string",
      "name": "string",
      "description": "string",
      "stats": {
        "totalMembers": "number",
        "activeMembers": "number",
        "totalHours": "number",
        "pendingTasks": "number",
        "approvedTasks": "number"
      },
      "achievements": [],
      "events": [],
      "topPerformers": [],
      "recentActivity": []
    }
  }
}

Volunteer Hours

GET /volunteer-hours

Get volunteer hours submissions.

Query Parameters:

  • clubId: Filter by club
  • userId: Filter by user
  • status: Filter by status (pending/approved/rejected/needs_info)
  • category: Filter by category
  • startDate: Filter by date range start
  • endDate: Filter by date range end
  • include: Include related data (comments,attachments)

Response:

{
  "status": "success",
  "data": {
    "submissions": [
      {
        "id": "string",
        "title": "string",
        "description": "string",
        "hours": "string",
        "category": "string",
        "status": "string",
        "userId": "string",
        "clubId": "string",
        "submittedAt": "string",
        "comments": [],
        "attachments": []
      }
    ]
  },
  "meta": {}
}

POST /volunteer-hours

Submit new volunteer hours.

Request:

{
  "title": "string",
  "description": "string",
  "hours": "string",
  "category": "string",
  "clubId": "string",
  "attachments": ["file"]
}

PATCH /volunteer-hours/:submissionId

Update submission status.

Request:

{
  "status": "string",
  "comment": "string"
}

Users

GET /users

Get users list.

Query Parameters:

  • role: Filter by role
  • clubId: Filter by club
  • include: Include related data (clubs,stats)
  • search: Search by name/email
  • status: Filter by status

Response:

{
  "status": "success",
  "data": {
    "users": [
      {
        "id": "string",
        "name": "string",
        "email": "string",
        "role": "string",
        "clubs": [],
        "stats": {
          "totalHours": "number",
          "completedTasks": "number"
        }
      }
    ]
  },
  "meta": {}
}

Statistics & Reports

GET /stats/club/:clubId

Get detailed club statistics.

Query Parameters:

  • period: Time period (daily/weekly/monthly/yearly)
  • startDate: Start date for custom range
  • endDate: End date for custom range

GET /stats/user/:userId

Get user statistics across all clubs.

Categories Reference

Volunteer Hours Categories

{
  "CLUB_PROGRAMS": "مهمة تخدم برامج أو مشاريع النادي",
  "UNIVERSITY_PARTICIPATION": "مهمة تخدم المشاركات داخل الجامعة",
  "EXTERNAL_PARTICIPATION": "مهمة تخدم المشاركات خارج الجامعة",
  "CLUB_INITIATIVES": "مهمة تخدم مبادرات النادي",
  "INTERNAL_ACTIVITIES": "مهمة تخدم الأنشطة الداخلية في النادي",
  "COMMUNITY_SERVICE": "مهمة تخدم المشاركات المجتمعية"
}

Status Codes

  • pending: قيد المراجعة
  • approved: تمت الموافقة
  • rejected: مرفوض
  • needs_info: تحتاج معلومات

Rate Limiting

  • 100 requests per minute per IP
  • 1000 requests per hour per user

File Upload

  • Supported formats: PDF, DOCX, XLSX, PNG, JPG
  • Max file size: 10MB
  • Max files per request: 5

Versioning

The API version is included in the URL path. Current version is v1.

⚠️ **GitHub.com Fallback** ⚠️