Skip to content

API_DOCUMENTATION.md

Latest commit

 

History

History
414 lines (317 loc) · 12.2 KB

API_DOCUMENTATION.md

File metadata and controls

414 lines (317 loc) · 12.2 KB
Raw

Backend API Documentation for Frontend Development

This document outlines all backend API endpoints, including methods, role requirements, path/query parameters, and expected request/response schemas (based on Joi validation). All authentication and authorization rules are strictly enforced.

Conventions

  • Role Requirements: The user must be authenticated and have one of the listed roles to access the endpoint.
  • Request Body: JSON structure for POST and PATCH requests is derived from Joi validation schemas.
  • Path Parameters: Represented as :param in URLs.

1. Authentication & User Management

1.1. User Authentication (/api/auth)

Endpoint Method Description Roles Params
/api/auth/login POST Authenticate a user and return a JWT token. None None

Request Body:

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

Responses:

{ "message": "Login successful", "token": "<JWT token>" }
{ "message": "Invalid email or password" }
{ "message": "Can't access deleted user" }
{ "message": "Server error" }
Endpoint Method Description Roles Params
/api/auth/signup POST Register a new user. Role-specific validation applies. None None

Request Bodies (per role):

👨‍🎓 Student

{
  "first_name": "string",
  "last_name": "string",
  "email": "string",
  "password": "string",
  "role": "Student",
  "university_id": "string"
}

👩‍🏫 Professor

{
  "first_name": "string",
  "last_name": "string",
  "email": "string",
  "password": "string",
  "role": "Professor",
  "university_id": "string",
  "faculty_id": "string"
}

🧑‍🏫 Teaching Assistant (TA)

{
  "first_name": "string",
  "last_name": "string",
  "email": "string",
  "password": "string",
  "role": "TA",
  "university_id": "string"
}

🧑‍💼 Staff

{
  "first_name": "string",
  "last_name": "string",
  "email": "string",
  "password": "string",
  "role": "Staff",
  "university_id": "string"
}

🏢 Vendor

{
  "company_name": "string",
  "email": "string",
  "password": "string",
  "role": "Vendor",
  "tax_card": "string",
  "logo": "string"
}

Response:

{
  "message": "<Role> registered successfully. Please check your email to verify your account.",
  "userId": "<newUserInstance._id or null>"
}
Endpoint Method Description Roles Params
/api/auth/verify-email GET Verify user email using a token None token (query param)

Request:

{ "token": "string" }

Responses:

{ "message": "Email verified successfully." }
{ "message": "Invalid or expired token." }

1.2. User Management (/api/users)

Endpoint Method Description Roles Params
/api/user/users GET Get all users. Admin None
/api/user/users POST Create a new Admin or Events Office user. Admin None
/api/user/verify POST Verify Staff, TA, or Professor accounts. Admin None
/api/user/:id DELETE Delete a user by ID. Admin :id (User ID)

Create Admin/Events Office Request Body (POST /api/users):

{
  "role": "Admin|EventsOffice",
  "email": "string",
  "password": "string",
  "first_name": "string",
  "last_name": "string",
  "university_id": "string"
}

Verify Staff/TA/Professor Request Body (POST /api/users/verify):

{
  "user_id": "string",
  "role": "Staff|TA|Professor"
}

2. 🎟️ Event Management (/api/events)

Endpoint Method Description Roles Params
/api/events GET View all events. None None
/api/events/upcoming GET View upcoming events. Student, Staff, TA, Professor, Events Office, Admin None
/api/events/:id DELETE Delete an event by ID. Events Office, Admin :id (Event ID)
/api/events/filter GET Filter events by query. None name, location, type, date
/api/events/registrations POST Register user for an event. Authenticated Users None
/api/events/registrations/:userId GET Get events registered by user. Authenticated Users :userId

Event Registration Request Body (POST /api/events/registrations):

{
  "id": "string",
  "name": "string",
  "email": "string",
  "event_id": "string"
}

Notes:

  • id is the user’s ID.
  • event_id is the ID of the event (e.g., workshop or trip) to register for.

Success Response:

{
  "message": "User successfully registered for the event",
  "registration": {
    "id": "string",
    "event_id": "string",
    "registrant": "string",
    "registration_status": true,
    "attendance_status": false
  }
}

2.1. Workshops (/api/events/workshops)

Endpoint Method Description Roles Params
/api/events/workshops GET View all workshops. None None
/api/events/workshops POST Create a new workshop. Professor None
/api/events/workshops/:id PATCH Update an existing workshop. Professor :id (Workshop ID)
/api/events/workshops/my-workshops/:professor_id GET View workshops created by logged-in professor. Professor :professor_id (Professor Id)
/api/events/workshops/confirmation/:id PATCH Approve or reject a workshop. Events Office :id (Workshop ID)

Confirmation Request Body:

{
  "confirmation_status": "ACCEPTED" | "REJECTED" | "CANCELLED" | "PENDING"
}

Workshop Schema:

{
  "name": "string",
  "description": "string",
  "location": "string",
  "confirmation_status": "ACCEPTED" | "REJECTED" | "CANCELLED" | "PENDING",
  "registration_deadline": "ISODate",
  "start_date": "ISODate",
  "end_date": "ISODate",
  "professor_name": "string",
  "responsible_faculty": "string",
  "agenda": "string",
  "capacity": 0
}

Notes:

  • confirmation_status is required only for PATCH requests (confirmation updates).

2.2. Bazaars (/api/events/bazaars)

Endpoint Method Description Roles Params
/api/events/bazaars POST Create a new bazaar. Events Office None
/api/events/bazaars/:id PATCH Update an existing bazaar. Events Office :id (Bazaar ID)
/api/events/bazaars/upcoming GET View upcoming bazaars. Vendor None

Bazaar Schema:

{
  "name": "string",
  "description": "string",
  "location": "string",
  "confirmation_status": "ACCEPTED" | "REJECTED" | "CANCELLED" | "PENDING",
  "registration_deadline": "ISODate",
  "start_date": "ISODate",
  "end_date": "ISODate",
  "vendor_ids": ["string"]
}

Notes:

  • confirmation_status is required only in PATCH.
  • vendor_ids defaults to an empty array ([]) if omitted.

2.3. Trips (/api/events/trips)

Endpoint Method Description Roles Params
/api/events/trips POST Create a new trip. Events Office None
/api/events/trips/:id PATCH Update a trip. Events Office :id (Trip ID)

Trip Schema:

{
  "name": "string",
  "description": "string",
  "location": "string",
  "confirmation_status": "ACCEPTED" | "REJECTED" | "CANCELLED" | "PENDING",
  "registration_deadline": "ISODate",
  "start_date": "ISODate",
  "end_date": "ISODate",
  "price": 0
}

Notes:

  • confirmation_status is required only for PATCH (confirmation updates).

2.4. Conferences (/api/events/conferences)

Endpoint Method Description Roles Params
/api/events/conferences POST Create a new conference. Events Office None
/api/events/conferences/:id PATCH Update a conference. Events Office :id (Conference ID)

Conference Schema:

{
  "name": "string",
  "description": "string",
  "location": "string",
  "confirmation_status": "ACCEPTED" | "REJECTED" | "CANCELLED" | "PENDING",
  "registration_deadline": "ISODate",
  "start_date": "ISODate",
  "end_date": "ISODate"
}

3. 🏋️ Sports Facilities

3.1. Gym Sessions (/api/gym-sessions)

Endpoint Method Description Roles Params
/api/gym-sessions GET View all gym sessions. Student, Staff, TA, Professor, Events Office None
/api/gym-sessions POST Create a gym session. Events Office None
/api/gym-sessions/:id PATCH Edit a gym session. Events Office :id
/api/gym-sessions/:id DELETE Cancel a gym session. Events Office :id
/api/gym-sessions/registrations POST Register for a gym session. Student, Staff, TA, Professor None

Gym Session Schema:

{
  "date": "ISODate",
  "time": "string",
  "duration": 0,
  "type": "string",
  "max_participants": 0
}

Notes:

  • duration is specified in minutes.
  • All fields are required for POST, optional for PATCH.

Registration Schema:

{
  "user_id": "string",
  "session_id": "string"
}

3.2. Court Reservations (/api/courts)

Endpoint Method Description Roles Params
/api/courts GET View all courts. Student None
/api/courts POST Reserve a court. Student None

Court Reservation Schema:

{
  "user_id": "string",
  "time_slot_id": "string"
}