API Overview

Introduction

The Extracurricular Management System (EMS) API is a RESTful API built with Spring Boot that provides comprehensive functionality for managing university extracurricular activities, events, and user interactions.

Base URL

The API is accessible at the following base URL:

http://localhost:8080/api

All API endpoints are prefixed with /api. For production deployments, replace localhost:8080 with your server’s hostname and port.

The default server port is 8080, but this can be configured via the server.port property in your application configuration.

API Conventions

Naming Conventions

The EMS API follows specific naming patterns for consistency:

camelCaseID Pattern

All entity identifiers use camelCase with an uppercase “ID” suffix:

userID - User identifier (Long)
eventID - Event identifier (Long)
activityID - Activity identifier (Long)
proposalID - Proposal identifier (Long)
registrationID - Registration identifier (Long)

Note that IDs use uppercase “ID”, not “Id”. For example, use userID, not userId.

Temporal Data Handling

The API uses LocalDate and LocalTime for temporal data without timezone support:

Date fields: Stored as LocalDate (e.g., eventDate, startDate)
Time fields: Stored as LocalTime (e.g., startTime, endTime)
Timestamps: Stored as LocalDateTime (e.g., createdAt, timestamp)

The API assumes all temporal data is in the server’s local timezone. No timezone conversion is performed.

Example temporal data in requests/responses:

{
  "eventDate": "2024-03-15",
  "startTime": "14:30:00",
  "endTime": "16:00:00",
  "createdAt": "2024-03-07T10:30:45"
}

Response Format

All API endpoints return a standardized response wrapper using the generic Response<T> class wrapped in Spring’s ResponseEntity.

Standard Response Structure

ResponseEntity<Response<T>>

The Response<T> object contains the following fields:

statusCode

integer

required

HTTP status code (e.g., 200, 201, 400, 404, 500)

message

string

required

Human-readable message describing the result

data

The response payload. Type varies by endpoint. May be null for operations that don’t return data.

timestamp

string (ISO 8601)

required

Server timestamp when the response was generated (LocalDateTime format)

errors

array of strings

List of error messages (only present in error responses)

Success Response Example

{
  "statusCode": 200,
  "message": "Event retrieved successfully",
  "data": {
    "eventID": 123,
    "eventName": "Spring Hackathon 2024",
    "eventDate": "2024-04-15",
    "startTime": "09:00:00",
    "endTime": "18:00:00",
    "location": "Engineering Building"
  },
  "timestamp": "2024-03-07T10:30:45"
}

Error Response Examples

The API uses the GlobalExceptionHandler to provide consistent error responses:

{
  "statusCode": 400,
  "message": "Email already in use.",
  "data": null,
  "timestamp": "2024-03-07T10:35:22"
}

HTTP Status Codes

The API uses standard HTTP status codes:

Status Code	Meaning	Usage
200	OK	Successful GET, PUT, or DELETE request
201	Created	Successful POST request that creates a resource
400	Bad Request	Invalid request data or business logic error
401	Unauthorized	Missing or invalid authentication token
403	Forbidden	Authenticated but lacking required permissions
404	Not Found	Resource does not exist
500	Internal Server Error	Unexpected server-side error

Pagination

List endpoints support pagination using standard query parameters:

page

integer

default:"0"

Zero-based page number

size

integer

default:"9"

Number of items per page

string

Optional search query to filter results

Paginated Response Example

{
  "statusCode": 200,
  "message": "Events retrieved successfully",
  "data": {
    "content": [
      { "eventID": 1, "eventName": "Event 1" },
      { "eventID": 2, "eventName": "Event 2" }
    ],
    "pageable": {
      "pageNumber": 0,
      "pageSize": 9
    },
    "totalElements": 45,
    "totalPages": 5,
    "last": false,
    "first": true,
    "numberOfElements": 9
  },
  "timestamp": "2024-03-07T10:40:30"
}

Content Type

All requests and responses use JSON format:

Content-Type: application/json

CORS

The API supports Cross-Origin Resource Sharing (CORS). The default allowed origin is:

http://localhost:5173

You can configure additional allowed origins via the cors.allowed-origins property in your application configuration.

Rate Limiting

Currently, the API does not implement rate limiting. This may be added in future versions.

API Versioning

The current API version is implicit in the /api prefix. Future versions may introduce version-specific endpoints (e.g., /api/v2).

Overview

Endpoints

Introduction

Base URL

API Conventions

Naming Conventions

camelCaseID Pattern

Temporal Data Handling

Response Format

Standard Response Structure

Success Response Example

Error Response Examples

HTTP Status Codes

Paginated Response Example

Content Type

CORS

Rate Limiting

API Versioning

Next Steps

Authentication

Endpoints

Build docs developers (and LLMs) love

Overview

Endpoints

​Introduction

​Base URL

​API Conventions

​Naming Conventions

​camelCaseID Pattern

​Temporal Data Handling

​Response Format

​Standard Response Structure

​Success Response Example

​Error Response Examples

​HTTP Status Codes

​Pagination

​Paginated Response Example

​Content Type

​CORS

​Rate Limiting

​API Versioning

​Next Steps

Authentication

Endpoints

Build docs developers (and LLMs) love

Introduction

Base URL

API Conventions

Naming Conventions

camelCaseID Pattern

Temporal Data Handling

Response Format

Standard Response Structure

Success Response Example

Error Response Examples

HTTP Status Codes

Pagination

Paginated Response Example

Content Type

CORS

Rate Limiting

API Versioning

Next Steps