Skip to content

API_DOCS.md

Latest commit

 

History

History
694 lines (651 loc) · 16.1 KB

API_DOCS.md

File metadata and controls

694 lines (651 loc) · 16.1 KB

API Docs

JWT Authentication

Token Usage

After successful login, include the JWT token in the Authorization header for protected routes:

Authorization: Bearer <your-jwt-token>

Token Contents

The JWT token contains:

  • User tokens: userId, role, email
  • Vendor tokens: vendorId, role (vendor), email, companyName

Token Expiration

Tokens expire after 24 hours and must be renewed by logging in again.

User Authentication

Registration

POST /api/users/register Body:

{
  "firstName": "string (required, 2-50 chars)",
  "lastName": "string (required, 2-50 chars)", 
  "email": "string (required, valid email)",
  "password": "string (required, min 6 chars)",
  "studentStaffId": "string (required)",
  "role": "string (required: student|staff|ta|professor)"
}

Response:

{
  "200": "Registration successful",
  "400": "Validation error",
  "409": "Email or Student/Staff ID already exists",
  "500": "Internal server error"
}

Login

POST /api/users/login Body:

{
  "email": "string (required)",
  "password": "string (required)"
}

Response:

{
  "200": {
    "message": "Login successful",
    "user": {
      "_id": "string",
      "firstName": "string",
      "lastName": "string",
      "email": "string",
      "role": "string",
      "studentStaffId": "string",
      "isConfirmed": true,
      "status": "active"
    },
    "token": "JWT_TOKEN_STRING"
  },
  "400": "Email and password required",
  "401": "Invalid credentials or account not verified",
  "500": "Internal server error"
}

Logout

POST /api/users/logout Headers:

Authorization: Bearer <token> (optional)

Response:

{
  "200": "Logout successful",
  "500": "Internal server error"
}

Vendor Authentication

Vendor Registration

POST /api/vendors/register Body:

{
  "companyName": "string (required, 2-100 chars)",
  "email": "string (required, valid email)",
  "password": "string (required, min 6 chars)"
}

Response:

{
  "201": "Vendor registration successful",
  "400": "Validation error",
  "409": "Email already registered",
  "500": "Internal server error"
}

Vendor Login

POST /api/vendors/login Body:

{
  "email": "string (required)",
  "password": "string (required)"
}

Response:

{
  "200": {
    "message": "Login successful",
    "vendor": {
      "_id": "string",
      "companyName": "string",
      "email": "string",
      "upcomingEvents": []
    },
    "token": "JWT_TOKEN_STRING"
  },
  "400": "Email and password required",
  "401": "Invalid credentials",
  "500": "Internal server error"
}

Vendor Logout

POST /api/vendors/logout Headers:

Authorization: Bearer <token> (optional)

Response:

{
  "200": "Vendor logout successful",
  "500": "Internal server error"
}

Get All Vendors

GET /api/vendors Response:

{
  "200": "Array of vendors",
  "500": "Internal server error"
}

Get Vendor by ID

GET /api/vendors/:id Response:

{
  "200": "Vendor data",
  "404": "Vendor not found",
  "500": "Internal server error"
}

Admin

Insert User Role (Requirement 5)

PATCH /api/admin/insertuserrole/:id Parameters: id: string Body:

{
  "userRole": "string"
}

Response:

{
  "200": "User role updated successfully",
  "400": "Invalid user role",
  "404": "User not found",
  "500": "Internal server error"
}

Events

Get All Upcoming Events

GET /api/events/upcoming Headers:

Authorization: Bearer <token>

Response:

{
  "200": {
    "message": "Upcoming events retrieved successfully",
    "totalEvents": 5,
    "events": [
      {
        "_id": "string",
        "name": "Tech Conference 2024",
        "type": "conference",
        "description": "Annual technology conference",
        "location": "Convention Center",
        "startDate": "2024-06-01T09:00:00.000Z",
        "endDate": "2024-06-03T17:00:00.000Z",
        "status": "upcoming",
        "createdBy": {
          "_id": "string",
          "firstName": "John",
          "lastName": "Doe",
          "email": "john.doe@guc.edu.eg",
          "role": "admin"
        },
        "vendors": [
          {
            "_id": "string",
            "companyName": "Tech Solutions Inc",
            "email": "contact@techsolutions.com"
          }
        ],
        "participatingVendors": [
          {
            "_id": "string",
            "companyName": "Tech Solutions Inc",
            "email": "contact@techsolutions.com"
          }
        ],
        "vendorCount": 1
      }
    ]
  },
  "401": "Access token required",
  "500": "Internal server error"
}

Get Upcoming Events by Type

GET /api/events/upcoming/:type Parameters:

  • type: string (workshop|trip|bazaar|conference|booth)

Headers:

Authorization: Bearer <token>

Response:

{
  "200": {
    "message": "Upcoming bazaar events retrieved successfully",
    "eventType": "bazaar",
    "totalEvents": 2,
    "events": [
      {
        "_id": "string",
        "name": "Spring Bazaar 2024",
        "type": "bazaar",
        "description": "Annual spring bazaar",
        "location": "Main Campus",
        "startDate": "2024-04-15T10:00:00.000Z",
        "endDate": "2024-04-17T18:00:00.000Z",
        "status": "upcoming",
        "createdBy": {
          "_id": "string",
          "firstName": "Jane",
          "lastName": "Smith",
          "email": "jane.smith@guc.edu.eg",
          "role": "eventsOffice"
        },
        "vendors": [
          {
            "_id": "string",
            "companyName": "Artisan Crafts",
            "email": "info@artisancrafts.com"
          },
          {
            "_id": "string",
            "companyName": "Tech Gadgets",
            "email": "sales@techgadgets.com"
          }
        ],
        "participatingVendors": [
          {
            "_id": "string",
            "companyName": "Artisan Crafts",
            "email": "info@artisancrafts.com"
          },
          {
            "_id": "string",
            "companyName": "Tech Gadgets",
            "email": "sales@techgadgets.com"
          }
        ],
        "vendorCount": 2
      }
    ]
  },
  "400": "Invalid event type",
  "401": "Access token required",
  "500": "Internal server error"
}

Search Events by Name or Type

GET /api/events/search Query Parameters:

  • query: string (optional) - Search by event name or description
  • type: string (optional) - Filter by event type (workshop|trip|bazaar|conference|booth)

Headers:

Authorization: Bearer <token>

Response:

{
  "200": {
    "message": "Events found successfully",
    "searchCriteria": {
      "query": "tech",
      "type": "conference"
    },
    "totalEvents": 2,
    "events": [
      {
        "_id": "string",
        "name": "Tech Conference 2024",
        "type": "conference",
        "description": "Annual technology conference",
        "location": "Convention Center",
        "startDate": "2024-06-01T09:00:00.000Z",
        "endDate": "2024-06-03T17:00:00.000Z",
        "status": "upcoming",
        "createdBy": {
          "_id": "string",
          "firstName": "John",
          "lastName": "Doe",
          "email": "john.doe@guc.edu.eg",
          "role": "admin"
        },
        "vendors": [],
        "createdAt": "2024-01-10T10:15:00.000Z",
        "updatedAt": "2024-01-10T10:15:00.000Z"
      }
    ]
  },
  "400": "Please provide either a search query or event type",
  "401": "Access token required",
  "500": "Internal server error"
}

Search Events by Professor Name

GET /api/events/search/professor Query Parameters:

  • professorName: string (required) - Professor's first name, last name, or full name

Headers:

Authorization: Bearer <token>

Response:

{
  "200": {
    "message": "Events found for professor: John Doe",
    "professorName": "John Doe",
    "totalEvents": 3,
    "events": [
      {
        "_id": "string",
        "name": "Advanced Algorithms Workshop",
        "type": "workshop",
        "description": "Workshop on advanced algorithms and data structures",
        "location": "Computer Lab 1",
        "startDate": "2024-05-15T14:00:00.000Z",
        "endDate": "2024-05-15T17:00:00.000Z",
        "status": "upcoming",
        "createdBy": {
          "_id": "string",
          "firstName": "John",
          "lastName": "Doe",
          "email": "john.doe@guc.edu.eg",
          "role": "professor"
        },
        "vendors": [],
        "createdAt": "2024-01-20T09:30:00.000Z",
        "updatedAt": "2024-01-20T09:30:00.000Z"
      }
    ]
  },
  "400": "Professor name is required",
  "401": "Access token required",
  "500": "Internal server error"
}

Event Registration

Register for Workshop/Trip

POST /api/registrations/register/:eventId Parameters:

  • eventId: string (required) - Event ID to register for

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Body:

{
  "participantName": "John Doe",
  "participantEmail": "john.doe@guc.edu.eg",
  "studentStaffId": "2021001234",
  "participantRole": "student",
  "emergencyContact": {
    "name": "Jane Doe",
    "phone": "+201234567890",
    "relationship": "Mother"
  },
  "specialRequirements": "Wheelchair accessible"
}

Required Fields:

  • participantName: string (required)
  • participantEmail: string (required)
  • studentStaffId: string (required)

Optional Fields:

  • participantRole: string (optional, defaults to "student")
  • emergencyContact: object (optional)
  • specialRequirements: string (optional)

Response:

{
  "201": {
    "message": "Registration successful",
    "registration": {
      "_id": "65a1b2c3d4e5f6789012345a",
      "event": {
        "_id": "65a1b2c3d4e5f6789012345b",
        "name": "Advanced Algorithms Workshop",
        "type": "workshop",
        "description": "Workshop on advanced algorithms",
        "location": "Computer Lab 1",
        "startDate": "2024-05-15T14:00:00.000Z",
        "endDate": "2024-05-15T17:00:00.000Z",
        "price": 0
      },
      "participantName": "John Doe",
      "participantEmail": "john.doe@guc.edu.eg",
      "studentStaffId": "2021001234",
      "participantRole": "student",
      "status": "registered",
      "registrationDate": "2024-01-25T10:30:00.000Z",
      "paymentStatus": "paid",
      "paymentAmount": 0
    }
  },
  "400": "Validation error / Registration deadline passed / Event at full capacity",
  "404": "Event not found",
  "409": "Already registered for this event",
  "401": "Access token required",
  "500": "Internal server error"
}

Get User's Registrations

GET /api/registrations/my-registrations?email=user@example.com Query Parameters:

  • email: string (required) - User's email address

Headers:

Authorization: Bearer <token>

Response:

{
  "200": {
    "message": "User registrations retrieved successfully",
    "email": "john.doe@guc.edu.eg",
    "totalRegistrations": 2,
    "registrations": [
      {
        "_id": "65a1b2c3d4e5f6789012345a",
        "event": {
          "_id": "65a1b2c3d4e5f6789012345b",
          "name": "Advanced Algorithms Workshop",
          "type": "workshop",
          "description": "Workshop on advanced algorithms",
          "location": "Computer Lab 1",
          "startDate": "2024-05-15T14:00:00.000Z",
          "endDate": "2024-05-15T17:00:00.000Z",
          "price": 0
        },
        "participantName": "John Doe",
        "participantEmail": "john.doe@guc.edu.eg",
        "studentStaffId": "2021001234",
        "participantRole": "student",
        "status": "registered",
        "registrationDate": "2024-01-25T10:30:00.000Z",
        "paymentStatus": "paid",
        "paymentAmount": 0
      }
    ]
  },
  "400": "Email is required",
  "401": "Access token required",
  "500": "Internal server error"
}

Get User's Registered Events (Upcoming and Past)

GET /api/registrations/my-events?email=user@example.com Query Parameters:

  • email: string (required) - User's email address

Headers:

Authorization: Bearer <token>

Response:

{
  "200": {
    "message": "User registered events retrieved successfully",
    "email": "john.doe@guc.edu.eg",
    "summary": {
      "totalRegistrations": 4,
      "upcomingEvents": 2,
      "pastEvents": 2
    },
    "upcomingEvents": [
      {
        "_id": "65a1b2c3d4e5f6789012345a",
        "registrationId": "65a1b2c3d4e5f6789012345a",
        "event": {
          "_id": "65a1b2c3d4e5f6789012345b",
          "name": "Advanced Algorithms Workshop",
          "type": "workshop",
          "description": "Workshop on advanced algorithms and data structures",
          "location": "Computer Lab 1",
          "startDate": "2024-05-15T14:00:00.000Z",
          "endDate": "2024-05-15T17:00:00.000Z",
          "price": 0,
          "capacity": 30
        },
        "participantName": "John Doe",
        "participantEmail": "john.doe@guc.edu.eg",
        "studentStaffId": "2021001234",
        "participantRole": "student",
        "status": "registered",
        "registrationDate": "2024-01-25T10:30:00.000Z",
        "paymentStatus": "paid",
        "paymentAmount": 0,
        "emergencyContact": {
          "name": "Jane Doe",
          "phone": "+201234567890",
          "relationship": "Mother"
        },
        "specialRequirements": "Wheelchair accessible",
        "eventStatus": "upcoming"
      }
    ],
    "pastEvents": [
      {
        "_id": "65a1b2c3d4e5f6789012345c",
        "registrationId": "65a1b2c3d4e5f6789012345c",
        "event": {
          "_id": "65a1b2c3d4e5f6789012345d",
          "name": "Spring Trip to Alexandria",
          "type": "trip",
          "description": "Educational trip to historical sites in Alexandria",
          "location": "Alexandria, Egypt",
          "startDate": "2024-03-10T08:00:00.000Z",
          "endDate": "2024-03-12T18:00:00.000Z",
          "price": 500,
          "capacity": 50
        },
        "participantName": "John Doe",
        "participantEmail": "john.doe@guc.edu.eg",
        "studentStaffId": "2021001234",
        "participantRole": "student",
        "status": "registered",
        "registrationDate": "2024-02-15T14:20:00.000Z",
        "paymentStatus": "paid",
        "paymentAmount": 500,
        "emergencyContact": {
          "name": "Jane Doe",
          "phone": "+201234567890",
          "relationship": "Mother"
        },
        "eventStatus": "past"
      }
    ]
  },
  "400": "Email is required",
  "401": "Access token required",
  "500": "Internal server error"
}

Cancel Registration

PATCH /api/registrations/cancel/:registrationId Parameters:

  • registrationId: string (required) - Registration ID to cancel

Headers:

Authorization: Bearer <token>

Response:

{
  "200": {
    "message": "Registration cancelled successfully",
    "registration": {
      "_id": "65a1b2c3d4e5f6789012345a",
      "status": "cancelled",
      "cancelledAt": "2024-01-25T15:45:00.000Z"
    }
  },
  "400": "Cannot cancel registration after event has started",
  "404": "Registration not found",
  "401": "Access token required",
  "500": "Internal server error"
}

Get Event Registrations (Admin/EventsOffice Only)

GET /api/registrations/event/:eventId Parameters:

  • eventId: string (required) - Event ID

Headers:

Authorization: Bearer <admin-token>

Response:

{
  "200": {
    "message": "Event registrations retrieved successfully",
    "event": {
      "_id": "65a1b2c3d4e5f6789012345b",
      "name": "Advanced Algorithms Workshop",
      "type": "workshop",
      "capacity": 30,
      "currentRegistrations": 15
    },
    "registrations": [
      {
        "_id": "65a1b2c3d4e5f6789012345a",
        "event": "65a1b2c3d4e5f6789012345b",
        "participantName": "John Doe",
        "participantEmail": "john.doe@guc.edu.eg",
        "studentStaffId": "2021001234",
        "participantRole": "student",
        "status": "registered",
        "registrationDate": "2024-01-25T10:30:00.000Z",
        "paymentStatus": "paid",
        "paymentAmount": 0
      }
    ]
  },
  "403": "Access denied. Insufficient permissions.",
  "404": "Event not found",
  "401": "Access token required",
  "500": "Internal server error"
}