LEGACY: Phase #1 API Docs (old)

Inma Clubs Management System API Documentation

Overview

This document serves as the official API documentation for the Inma Clubs Management System. It defines the standard patterns and structures that all API endpoints must follow to ensure consistency across the system.

Base URL

/api/v1

Authentication

[Authentication endpoints will be documented here]

Common Query Parameters

Pagination

All list endpoints support pagination with the following parameters:

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

Filtering

Filtering is supported through query parameters. Each resource has its specific filterable fields, but the pattern remains consistent:

?fieldName=value
?fieldName[operator]=value

Supported operators:

• eq: Equal to (default if no operator specified)
• ne: Not equal to
• gt: Greater than
• gte: Greater than or equal to
• lt: Less than
• lte: Less than or equal to
• in: Value is in array
• nin: Value is not in array

Example:

?status=active
?hours[gt]=10
?category[in]=CLUB_PROGRAMS,UNIVERSITY_PARTICIPATION
?startDate[gte]=2024-01-01&endDate[lte]=2024-12-31

Search

Search is available for primary identifiers:

• Clubs: name field only
• Users: name, email, uniId, nationalId fields
• Tasks: title field only

?search=term

Sorting

Sort results using the sort parameter:

?sort=field1,-field2

Prefix with - for descending order.

Field Selection

Select specific fields to return:

?fields=field1,field2,field3

Including Relations

Include related resources:

?include=relation1,relation2

Response Format

Success Response

{
    "status": "success",
    "data": {
        // Resource data or array of resources
    },
    "meta": {
        "page": 1,
        "limit": 10,
        "total": 100,
        "totalPages": 10
    }
}

Error Response

{
    "status": "error",
    "error": {
        "code": "ERROR_CODE",
        "message": "Error description",
        "details": {
            // Optional additional error details
        }
    }
}

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
• 422 Unprocessable Entity: Validation error
• 429 Too Many Requests: Rate limit exceeded

Server Error Codes

• 500 Internal Server Error: Unexpected server error

Standard Endpoint Patterns

List Resources (GET /resources)

Query Parameters:

• All common parameters (pagination, filtering, search, sort, fields, include)

Example:

GET /api/v1/clubs?page=1&limit=10&sort=-createdAt&fields=id,name,description&include=events

Get Single Resource (GET /resources/:id)

Query Parameters:

• fields: Select specific fields
• include: Include related resources

Example:

GET /api/v1/clubs/123?include=events,members&fields=id,name,description

Create Resource (POST /resources)

Request Body:

{
    "field1": "value1",
    "field2": "value2"
}

Update Resource (PATCH /resources/:id)

Request Body:

{
    "field1": "newValue1",
    "field2": "newValue2"
}

Delete Resource (DELETE /resources/:id)

Returns 204 No Content on success.

Resource-Specific Endpoints

Clubs

GET /clubs

• Search: name field only
• Include: events, members, stats
• Filter by:
  • status: Club status (active/inactive)
  • createdAt: Creation date range

GET /clubs/:id

• Include: events, members, stats, achievements

Tasks

GET /tasks

• Search: title field only
• Include: clubMembership
• Filter by:
  • clubMembershipId: Associated membership
  • status: Task status (accepted/pending/denied)
  • category: Task category (CLUB_PROGRAMS/UNIVERSITY_PARTICIPATION/EXTERNAL_PARTICIPATION/CLUB_INITIATIVES/INTERNAL_ACTIVITIES/COMMUNITY_SERVICE)
  • volunteeredSeconds: Hours range
  • createdAt: Creation date range

GET /tasks/:id

• Include: clubMembership

Users

GET /users

• Search: name, email, uniId, nationalId fields
• Include: clubs, stats
• Filter by:
  • globalRole: User role (inmaAdmin/uniAdmin/user)
  • status: Account status
  • createdAt: Account creation date range

Club Memberships

GET /club-memberships

• Include: user, club
• Filter by:
  • clubId: Associated club
  • userId: Associated user
  • role: Membership role (clubAdmin/hr/member)
  • joinedAt: Join date range

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.

Best Practices for Implementation

1. All endpoints must support the common query parameters where applicable
2. Response formats must be consistent across all endpoints
3. Error responses must follow the standard error format
4. Filtering, sorting, and searching should be implemented consistently
5. Include proper validation for all input parameters
6. Document all available filters, includes, and sortable fields for each endpoint
7. Use proper HTTP status codes
8. Implement proper error handling and validation
9. Follow RESTful principles for endpoint design
10. Maintain consistent naming conventions across all endpoints

Frontend Query Tutorial

Basic Query Examples

1. Get first page of clubs with basic info:

const response = await fetch(
    '/api/v1/clubs?page=1&limit=10&fields=id,name,description',
);

2. Search for clubs with specific name:

const response = await fetch('/api/v1/clubs?search=tech');

3. Get clubs with specific status:

const response = await fetch('/api/v1/clubs?status=active');

4. Filter tasks by date range and category:

const response = await fetch(
    '/api/v1/tasks?createdAt[gte]=2024-01-01&createdAt[lte]=2024-01-31&category=CLUB_PROGRAMS',
);

5. Get user with specific role and include their clubs:

const response = await fetch(
    '/api/v1/users?globalRole=inmaAdmin&include=clubs',
);

6. Advanced filtering with multiple conditions:

const response = await fetch(
    '/api/v1/tasks?status[in]=accepted,pending&volunteeredSeconds[gt]=3600&sort=-createdAt',
);

Building Complex Queries

You can combine multiple parameters to build complex queries:

const queryParams = new URLSearchParams({
    page: '1',
    limit: '20',
    sort: '-createdAt',
    fields: 'id,name,description',
    include: 'members',
    'status[in]': 'active,pending',
    'createdAt[gte]': '2024-01-01',
});

const response = await fetch(`/api/v1/clubs?${queryParams.toString()}`);

Handling Pagination

async function fetchPaginatedData(endpoint, page = 1, limit = 10) {
    const response = await fetch(`${endpoint}?page=${page}&limit=${limit}`);
    const data = await response.json();

    return {
        items: data.data,
        pagination: data.meta,
    };
}