openapi.yaml

openapi: 3.0.3
info:
  title: Eventra API
  description: |
    Comprehensive API for the Eventra event management system.
    
    Eventra provides a complete platform for managing events, attendees, RSVPs, 
    check-ins, and analytics with role-based access control and real-time features.
    
    ## Authentication
    Most endpoints require JWT authentication using the `Authorization: Bearer <token>` header.
    
    ## Rate Limiting
    - Authenticated users: 1000 requests/hour
    - Anonymous users: 100 requests/hour
    
    ## Support
    - Email: api-support@eventra.com
    - Discord: https://discord.gg/eventra
    - GitHub: https://github.com/SandeepVashishtha/Eventra
  version: "1.0.0"
  contact:
    name: Eventra API Support
    email: api-support@eventra.com
    url: https://docs.eventra.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  termsOfService: https://eventra.com/terms

servers:
  - url: https://api.eventra.com
    description: Production server
  - url: http://localhost:8080
    description: Development server

security:
  - BearerAuth: []

paths:
  # Authentication endpoints
  /api/auth/register:
    post:
      tags:
        - Authentication
      summary: Register new user
      description: Create a new user account
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserRegistration'
      responses:
        '201':
          description: User registered successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/AuthResponse'
        '409':
          $ref: '#/components/responses/ConflictError'
        '422':
          $ref: '#/components/responses/ValidationError'

  /api/auth/login:
    post:
      tags:
        - Authentication
      summary: User login
      description: Authenticate user and get access token
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/AuthResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'

  /api/auth/me:
    get:
      tags:
        - Authentication
      summary: Get current user profile
      description: Retrieve the authenticated user's profile information
      responses:
        '200':
          description: User profile retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/UnauthorizedError'

  # Events endpoints
  /api/events:
    get:
      tags:
        - Events
      summary: Get events list
      description: Retrieve a paginated list of events with filtering options
      security: []
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/SortParam'
        - $ref: '#/components/parameters/OrderParam'
        - name: category
          in: query
          schema:
            $ref: '#/components/schemas/EventCategory'
        - name: isPublic
          in: query
          schema:
            type: boolean
        - name: search
          in: query
          schema:
            type: string
            maxLength: 100
      responses:
        '200':
          description: Events retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          events:
                            type: array
                            items:
                              $ref: '#/components/schemas/Event'
                          pagination:
                            $ref: '#/components/schemas/PaginationInfo'

    post:
      tags:
        - Events
      summary: Create new event
      description: Create a new event (requires authentication)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEventRequest'
      responses:
        '201':
          description: Event created successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/Event'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'

  /api/events/{eventId}:
    get:
      tags:
        - Events
      summary: Get event details
      description: Retrieve detailed information about a specific event
      security: []
      parameters:
        - $ref: '#/components/parameters/EventIdParam'
      responses:
        '200':
          description: Event details retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/Event'
        '404':
          $ref: '#/components/responses/NotFoundError'

    put:
      tags:
        - Events
      summary: Update event
      description: Update an existing event (organizer only)
      parameters:
        - $ref: '#/components/parameters/EventIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEventRequest'
      responses:
        '200':
          description: Event updated successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/Event'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'

  # RSVP endpoints
  /api/events/{eventId}/rsvp:
    post:
      tags:
        - RSVP
      summary: Register for event
      description: RSVP for an event
      parameters:
        - $ref: '#/components/parameters/EventIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRSVPRequest'
      responses:
        '201':
          description: RSVP created successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/RSVP'
        '409':
          $ref: '#/components/responses/ConflictError'
        '422':
          $ref: '#/components/responses/ValidationError'

    get:
      tags:
        - RSVP
      summary: Get user's RSVP
      description: Get current user's RSVP status for an event
      parameters:
        - $ref: '#/components/parameters/EventIdParam'
      responses:
        '200':
          description: RSVP status retrieved
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/RSVP'

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  parameters:
    EventIdParam:
      name: eventId
      in: path
      required: true
      schema:
        type: integer
        format: int64
        minimum: 1
      description: Event ID

    PageParam:
      name: page
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1
      description: Page number

    LimitParam:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
      description: Items per page

    SortParam:
      name: sort
      in: query
      schema:
        type: string
        enum: [title, startDate, createdAt, updatedAt]
        default: createdAt
      description: Sort field

    OrderParam:
      name: order
      in: query
      schema:
        type: string
        enum: [asc, desc]
        default: desc
      description: Sort order

  schemas:
    SuccessResponse:
      type: object
      required:
        - success
        - timestamp
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: "Operation completed successfully"
        timestamp:
          type: string
          format: date-time
          example: "2024-01-15T10:30:00Z"

    ErrorResponse:
      type: object
      required:
        - success
        - error
        - timestamp
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              example: "VALIDATION_ERROR"
            message:
              type: string
              example: "Invalid input data"
            details:
              type: array
              items:
                type: string
              example: ["Email is required", "Password too short"]
            field:
              type: string
              example: "email"
        timestamp:
          type: string
          format: date-time
          example: "2024-01-15T10:30:00Z"

    PaginationInfo:
      type: object
      required:
        - page
        - limit
        - total
        - totalPages
        - hasNext
        - hasPrev
      properties:
        page:
          type: integer
          minimum: 1
          example: 1
        limit:
          type: integer
          minimum: 1
          example: 20
        total:
          type: integer
          minimum: 0
          example: 150
        totalPages:
          type: integer
          minimum: 0
          example: 8
        hasNext:
          type: boolean
          example: true
        hasPrev:
          type: boolean
          example: false

    User:
      type: object
      required:
        - id
        - email
        - name
        - role
        - isEmailVerified
        - createdAt
      properties:
        id:
          type: integer
          format: int64
          example: 1
        email:
          type: string
          format: email
          example: "user@example.com"
        name:
          type: string
          minLength: 2
          maxLength: 100
          example: "John Doe"
        organization:
          type: string
          maxLength: 100
          example: "Tech Corp"
        role:
          $ref: '#/components/schemas/UserRole'
        isEmailVerified:
          type: boolean
          example: true
        avatar:
          type: string
          format: uri
          example: "https://example.com/avatars/user1.jpg"
        createdAt:
          type: string
          format: date-time
          example: "2024-01-15T10:30:00Z"
        updatedAt:
          type: string
          format: date-time
          example: "2024-01-15T15:45:00Z"

    UserRole:
      type: string
      enum:
        - USER
        - ORGANIZER
        - ADMIN
        - SUPER_ADMIN
      example: "USER"

    UserRegistration:
      type: object
      required:
        - email
        - password
        - name
      properties:
        email:
          type: string
          format: email
          example: "user@example.com"
        password:
          type: string
          minLength: 8
          maxLength: 128
          example: "securePassword123"
        name:
          type: string
          minLength: 2
          maxLength: 100
          example: "John Doe"
        organization:
          type: string
          maxLength: 100
          example: "Tech Corp"

    LoginRequest:
      type: object
      required:
        - email
        - password
      properties:
        email:
          type: string
          format: email
          example: "user@example.com"
        password:
          type: string
          example: "securePassword123"

    AuthResponse:
      type: object
      required:
        - user
        - token
        - refreshToken
        - expiresIn
      properties:
        user:
          $ref: '#/components/schemas/User'
        token:
          type: string
          example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
        refreshToken:
          type: string
          example: "def50200e54b9..."
        expiresIn:
          type: integer
          example: 3600

    Event:
      type: object
      required:
        - id
        - title
        - startDate
        - endDate
        - timezone
        - capacity
        - isPublic
        - category
        - status
        - createdAt
      properties:
        id:
          type: integer
          format: int64
          example: 1
        title:
          type: string
          minLength: 3
          maxLength: 200
          example: "Tech Conference 2024"
        description:
          type: string
          maxLength: 5000
          example: "Annual technology conference featuring latest innovations"
        slug:
          type: string
          pattern: '^[a-z0-9-]+$'
          example: "tech-conference-2024"
        startDate:
          type: string
          format: date-time
          example: "2024-12-01T09:00:00Z"
        endDate:
          type: string
          format: date-time
          example: "2024-12-01T18:00:00Z"
        timezone:
          type: string
          example: "America/New_York"
        location:
          $ref: '#/components/schemas/EventLocation'
        isVirtual:
          type: boolean
          example: false
        virtualLink:
          type: string
          format: uri
          example: "https://zoom.us/j/123456789"
        capacity:
          type: integer
          minimum: 1
          maximum: 100000
          example: 500
        isPublic:
          type: boolean
          example: true
        requiresApproval:
          type: boolean
          example: false
        registrationOpen:
          type: boolean
          example: true
        registrationStart:
          type: string
          format: date-time
          example: "2024-10-01T00:00:00Z"
        registrationEnd:
          type: string
          format: date-time
          example: "2024-11-30T23:59:59Z"
        category:
          $ref: '#/components/schemas/EventCategory'
        tags:
          type: array
          items:
            type: string
          example: ["technology", "innovation", "networking"]
        ticketTiers:
          type: array
          items:
            $ref: '#/components/schemas/TicketTier'
        organizer:
          $ref: '#/components/schemas/EventOrganizer'
        stats:
          $ref: '#/components/schemas/EventStats'
        status:
          $ref: '#/components/schemas/EventStatus'
        createdAt:
          type: string
          format: date-time
          example: "2024-01-15T10:30:00Z"
        updatedAt:
          type: string
          format: date-time
          example: "2024-01-20T14:22:00Z"

    EventCategory:
      type: string
      enum:
        - CONFERENCE
        - WORKSHOP
        - MEETUP
        - WEBINAR
        - SOCIAL
        - SPORTS
        - CULTURAL
        - BUSINESS
        - CHARITY
        - OTHER
      example: "CONFERENCE"

    EventStatus:
      type: string
      enum:
        - DRAFT
        - ACTIVE
        - PAUSED
        - CANCELLED
        - COMPLETED
      example: "ACTIVE"

    EventLocation:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          example: "Convention Center"
        address:
          type: string
          example: "123 Main St, New York, NY 10001"
        coordinates:
          type: object
          properties:
            latitude:
              type: number
              format: double
              example: 40.7128
            longitude:
              type: number
              format: double
              example: -74.0060

    TicketTier:
      type: object
      required:
        - id
        - name
        - price
        - capacity
      properties:
        id:
          type: integer
          format: int64
          example: 1
        name:
          type: string
          example: "General Admission"
        price:
          type: number
          format: double
          minimum: 0
          example: 99.99
        capacity:
          type: integer
          minimum: 1
          example: 400
        description:
          type: string
          example: "Standard conference access"

    EventOrganizer:
      type: object
      required:
        - id
        - name
        - email
      properties:
        id:
          type: integer
          format: int64
          example: 1
        name:
          type: string
          example: "John Doe"
        email:
          type: string
          format: email
          example: "john@example.com"
        organization:
          type: string
          example: "Tech Corp"

    EventStats:
      type: object
      properties:
        totalRSVPs:
          type: integer
          minimum: 0
          example: 245
        confirmedAttendees:
          type: integer
          minimum: 0
          example: 230
        checkedIn:
          type: integer
          minimum: 0
          example: 180
        waitlistCount:
          type: integer
          minimum: 0
          example: 15

    CreateEventRequest:
      type: object
      required:
        - title
        - startDate
        - endDate
        - timezone
        - capacity
        - category
      properties:
        title:
          type: string
          minLength: 3
          maxLength: 200
          example: "Tech Conference 2024"
        description:
          type: string
          maxLength: 5000
          example: "Annual technology conference"
        startDate:
          type: string
          format: date-time
          example: "2024-12-01T09:00:00Z"
        endDate:
          type: string
          format: date-time
          example: "2024-12-01T18:00:00Z"
        timezone:
          type: string
          example: "America/New_York"
        location:
          $ref: '#/components/schemas/EventLocation'
        isVirtual:
          type: boolean
          default: false
        virtualLink:
          type: string
          format: uri
        capacity:
          type: integer
          minimum: 1
          maximum: 100000
          example: 500
        isPublic:
          type: boolean
          default: true
        requiresApproval:
          type: boolean
          default: false
        registrationStart:
          type: string
          format: date-time
        registrationEnd:
          type: string
          format: date-time
        category:
          $ref: '#/components/schemas/EventCategory'
        tags:
          type: array
          items:
            type: string
          maxItems: 10
        ticketTiers:
          type: array
          items:
            type: object
            required:
              - name
              - price
              - capacity
            properties:
              name:
                type: string
              price:
                type: number
                format: double
                minimum: 0
              capacity:
                type: integer
                minimum: 1
              description:
                type: string

    UpdateEventRequest:
      allOf:
        - $ref: '#/components/schemas/CreateEventRequest'
      # All fields are optional for updates

    RSVP:
      type: object
      required:
        - id
        - eventId
        - userId
        - status
        - responseDate
        - createdAt
      properties:
        id:
          type: integer
          format: int64
          example: 1
        eventId:
          type: integer
          format: int64
          example: 1
        userId:
          type: integer
          format: int64
          example: 1
        status:
          $ref: '#/components/schemas/RSVPStatus'
        ticketTierId:
          type: integer
          format: int64
          example: 1
        ticketTier:
          $ref: '#/components/schemas/TicketTier'
        responseDate:
          type: string
          format: date-time
          example: "2024-10-15T10:30:00Z"
        checkedIn:
          type: boolean
          example: false
        checkedInAt:
          type: string
          format: date-time
        qrCode:
          type: string
          example: "EVT001-USR001-TIK001"
        specialRequests:
          type: string
          maxLength: 1000
          example: "Vegetarian meal preference"
        paymentStatus:
          $ref: '#/components/schemas/PaymentStatus'
        createdAt:
          type: string
          format: date-time
          example: "2024-10-15T10:30:00Z"
        updatedAt:
          type: string
          format: date-time
          example: "2024-10-15T10:30:00Z"

    RSVPStatus:
      type: string
      enum:
        - confirmed
        - pending
        - declined
        - waitlist
        - cancelled
        - expired
      example: "confirmed"

    PaymentStatus:
      type: string
      enum:
        - pending
        - paid
        - failed
        - refunded
        - partial
      example: "paid"

    CreateRSVPRequest:
      type: object
      required:
        - ticketTierId
      properties:
        ticketTierId:
          type: integer
          format: int64
          example: 1
        specialRequests:
          type: string
          maxLength: 1000
          example: "Vegetarian meal preference"
        additionalData:
          type: object
          additionalProperties: true

  responses:
    UnauthorizedError:
      description: Authentication required or invalid token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              code: "INVALID_TOKEN"
              message: "JWT token is invalid or expired"
            timestamp: "2024-01-15T10:30:00Z"

    ForbiddenError:
      description: Access denied - insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              code: "INSUFFICIENT_PERMISSIONS"
              message: "User lacks required permissions"
            timestamp: "2024-01-15T10:30:00Z"

    NotFoundError:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              code: "RESOURCE_NOT_FOUND"
              message: "The requested resource does not exist"
            timestamp: "2024-01-15T10:30:00Z"

    ConflictError:
      description: Resource conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              code: "RESOURCE_CONFLICT"
              message: "Resource already exists or conflicts with existing data"
            timestamp: "2024-01-15T10:30:00Z"

    ValidationError:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              code: "VALIDATION_ERROR"
              message: "Invalid input data"
              details:
                - "Email is required"
                - "Password must be at least 8 characters"
            timestamp: "2024-01-15T10:30:00Z"

    RateLimitError:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              code: "RATE_LIMIT_EXCEEDED"
              message: "Too many requests in time window"
            timestamp: "2024-01-15T10:30:00Z"
      headers:
        X-RateLimit-Limit:
          description: Request limit per hour
          schema:
            type: integer
            example: 1000
        X-RateLimit-Remaining:
          description: Remaining requests in current window
          schema:
            type: integer
            example: 999
        X-RateLimit-Reset:
          description: Time when rate limit resets (Unix timestamp)
          schema:
            type: integer
            example: 1640995200
        Retry-After:
          description: Seconds to wait before retrying
          schema:
            type: integer
            example: 60

tags:
  - name: Authentication
    description: User authentication and profile management
  - name: Events
    description: Event creation and management
  - name: RSVP
    description: Event registration and RSVP management
  - name: Check-in
    description: Event check-in and QR code functionality
  - name: Analytics
    description: Event analytics and reporting
  - name: Feedback
    description: Post-event feedback and surveys
  - name: Admin
    description: Administrative operations