Document of my DSAS CCA API

Overview

The DSAS CCA (Co-Curricular Activities) API provides programmatic access to information about clubs, activities, and staff at DSAS. This RESTful API allows developers to retrieve comprehensive details about clubs, filter activities by various parameters, and access staff information.

Base URL

1

https://dsas-cca.jamesflare.com

Authentication

The API endpoints are publicly accessible and do not require authentication for read operations.

Rate Limiting

Please be considerate with your API usage. Excessive requests may be rate-limited.

Endpoints

Club & Activity Endpoints

1. List All Clubs

1

GET /v1/activity/list

Description: Returns a list of all clubs with their names and photos.

Response Format:

2. Filter Clubs by Category

1

GET /v1/activity/list?category={categoryName}

Description: Returns clubs that belong to the specified category.

Parameters:

• category (string): Name of the category (e.g., “Expressive Arts”, “STEAM”)

Response Format: Same as List All Clubs endpoint, filtered by the specified category.

3. Filter Clubs by Academic Year

1

GET /v1/activity/list?academicYear={academicYear}

Description: Returns clubs from the specified academic year.

Parameters:

• academicYear (string): Academic year in the format YYYY/YYYY (e.g., “2022/2023”)

Response Format: Same as List All Clubs endpoint, filtered by the specified academic year.

4. Filter Clubs by Grade

1

GET /v1/activity/list?grade={grade}

Description: Returns clubs that accept students from the specified grade.

Parameters:

• grade (number): Grade level (1-12)

Response Format: Same as List All Clubs endpoint, filtered to include only clubs where the specified grade falls within the club’s grade range.

5. Filter Clubs by isStudentLed

1

GET /v1/activity/list?isStudentLed={true|false}

Description: Returns clubs that accept students from the specified grade.

Parameters:

• isStudentLed (boolean): true or false

Response Format: Same as List All Clubs endpoint, filtered by isStudentLed.

6. Available Categories

1

GET /v1/activity/category

Description: Returns a list of all available club categories with the count of clubs in each category.

Response Format:

7. Available Academic Years

1

GET /v1/activity/academicYear

Description: Returns a list of all available academic years with the count of clubs in each year.

Response Format:

8. Get Club Details

1

GET /v1/activity/{activityId}

Description: Returns detailed information about a specific club.

Parameters:

• activityId (string): The ID of the club (1-4 digits)

Response Format:

Staff Endpoints

1. Get All Staff

1

GET /v1/staffs

Description: Returns a list of all staff members with their IDs and names.

Response Format:

Combining Filters

The Activity List endpoint supports combining multiple filters to refine your search:

1

GET /v1/activity/list?category=STEAM&grade=10&academicYear=2023/2024&isStudentLed=true

This would return all sports clubs for the 2022/2023 academic year that accept grade 10 students.

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of requests:

• 200 OK: Request succeeded
• 400 Bad Request: Invalid parameters were provided
• 404 Not Found: The requested resource was not found
• 500 Internal Server Error: Server-side error occurred

Error responses include a JSON object with an error field describing the issue:

For invalid category or academicYear parameters, the response includes available options:

Caching

The API implements caching to improve performance:

• Response objects include a cache field indicating cache status:

  • "HIT": Response came from the cache
  • "MISS": Response was freshly fetched from the source
  • "ERROR": An error occurred during cache retrieval or data fetching

• Response objects also include a lastCheck timestamp indicating when the data was last updated.

Examples

Get details for club that has id 3350

Request:

1

GET /v1/activity/3350

Response:

Get all available categories

Request:

1

GET /v1/activity/category

Response:

Get all staff members

Request:

1

GET /v1/staffs

Response:

Get STEAM student-led clubs in academic year 2023/2024 that accept grade 10 students

Request:

1

GET /v1/activity/list?category=STEAM&grade=10&academicYear=2023/2024&isStudentLed=true

Response:

Implementation Notes

• When filtering by grade, clubs with null grade values are excluded from the results
• Academic year format must strictly follow the YYYY/YYYY pattern
• All API endpoints support CORS for cross-origin requests