Avokkado Play Events Controller REST API Design

openapi.yml

openapi: 3.0.3
info:
  title: Events API
  version: 1.0.0

servers:
  - url: https://api.example.com

tags:
  - name: Events
    description: Match-event operations

paths:
  /events:
    get:
      tags: [Events]
      summary: List events
      parameters:
        - name: matchId
          in: query
          description: Filter by match
          schema: { type: integer }
        - name: teamId
          in: query
          description: Filter by team
          schema: { type: integer }
      responses:
        '200':
          description: Array of events
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/EventDto' }

  /events/{eventId}:
    get:
      tags: [Events]
      summary: Get event by ID
      parameters:
        - $ref: '#/components/parameters/EventId'
      responses:
        '200':
          description: Event found
          content:
            application/json:
              schema: { $ref: '#/components/schemas/EventDto' }

    delete:
      tags: [Events]
      summary: Delete event
      parameters:
        - $ref: '#/components/parameters/EventId'
      responses:
        '204': { description: Deleted }

  /events/card:
    post:
      tags: [Events]
      summary: Create card event
      requestBody: { $ref: '#/components/requestBodies/CreateCardEventDto' }
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CardEventDto' }

  /events/card/{eventId}:
    put:
      tags: [Events]
      summary: Update card event
      parameters:
        - $ref: '#/components/parameters/EventId'
      requestBody: { $ref: '#/components/requestBodies/CreateCardEventDto' }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CardEventDto' }

  /events/goal:
    post:
      tags: [Events]
      summary: Create goal event
      requestBody: { $ref: '#/components/requestBodies/CreateGoalEventDto' }
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/GoalEventDto' }

  /events/goal/{eventId}:
    put:
      tags: [Events]
      summary: Update goal event
      parameters:
        - $ref: '#/components/parameters/EventId'
      requestBody: { $ref: '#/components/requestBodies/CreateGoalEventDto' }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema: { $ref: '#/components/schemas/GoalEventDto' }

  /events/ejected:
    post:
      tags: [Events]
      summary: Create ejected event
      requestBody: { $ref: '#/components/requestBodies/CreateEjectedEventDto' }
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/EjectedEventDto' }

  /events/ejected/{eventId}:
    put:
      tags: [Events]
      summary: Update ejected event
      parameters:
        - $ref: '#/components/parameters/EventId'
      requestBody: { $ref: '#/components/requestBodies/CreateEjectedEventDto' }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema: { $ref: '#/components/schemas/EjectedEventDto' }

  /events/foul:
    post:
      tags: [Events]
      summary: Create foul event
      requestBody: { $ref: '#/components/requestBodies/CreateFoulEventDto' }
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/FoulEventDto' }

  /events/foul/{eventId}:
    put:
      tags: [Events]
      summary: Update foul event
      parameters:
        - $ref: '#/components/parameters/EventId'
      requestBody: { $ref: '#/components/requestBodies/CreateFoulEventDto' }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema: { $ref: '#/components/schemas/FoulEventDto' }

components:
  parameters:
    EventId:
      name: eventId
      in: path
      required: true
      description: Numeric ID of the event
      schema: { type: integer }

  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              message: { type: string }

  requestBodies:
    CreateCardEventDto:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateCardEventDto'
                    
    CreateGoalEventDto:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateGoalEventDto'
                    
    CreateEjectedEventDto:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateEjectedEventDto'
                    
                    
    CreateFoulEventDto:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateFoulEventDto'

  schemas:
    CardEventDto:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
          example: 42
        matchId:
          type: integer
          example: 99
        time:
          type: string
          format: date-time
          example: '2025-07-03T17:54:17.401Z'
        card:
          type: object
          properties:
            playerId:
              type: integer
            type:
              type: integer
              
    CreateCardEventDto:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
          example: 42
        matchId:
          type: integer
          example: 99
        time:
          type: string
          format: date-time
          example: '2025-07-03T17:54:17.401Z'
        playerId:
          type: integer
        type:
          type: integer
              
    GoalEventDto:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
          example: 42
        matchId:
          type: integer
          example: 99
        time:
          type: string
          format: date-time
          example: '2025-07-03T17:54:17.401Z'
        goal:
          type: object
          properties:
            scorerId:
              type: integer
            assisterId:
              type: integer
              nullable: true
              
    CreateGoalEventDto:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
          example: 42
        matchId:
          type: integer
          example: 99
        time:
          type: string
          format: date-time
          example: '2025-07-03T17:54:17.401Z'
        playerId:
          type: integer
        type:
          type: integer
              
    EjectedEventDto:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
          example: 42
        matchId:
          type: integer
          example: 99
        time:
          type: string
          format: date-time
          example: '2025-07-03T17:54:17.401Z'
        ejected:
          type: object
          properties:
            playerId:
              type: integer
            missingMatches:
              type: integer
              minimum: 0
              
    CreateEjectedEventDto:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
          example: 42
        matchId:
          type: integer
          example: 99
        time:
          type: string
          format: date-time
          example: '2025-07-03T17:54:17.401Z'
        playerId:
          type: integer
        type:
          type: integer
              
    FoulEventDto:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
          example: 42
        matchId:
          type: integer
          example: 99
        time:
          type: string
          format: date-time
          example: '2025-07-03T17:54:17.401Z'
        foul:
          type: object
          properties:
            playerId:
              type: integer
            duration:
              type: integer
              description: Penalty box time (minutes)
              
    CreateFoulEventDto:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
          example: 42
        matchId:
          type: integer
          example: 99
        time:
          type: string
          format: date-time
          example: '2025-07-03T17:54:17.401Z'
        playerId:
          type: integer
        type:
          type: integer
              
    EventDto:
      description: A match event.
      oneOf:
        - $ref: '#/components/schemas/CardEventDto'
        - $ref: '#/components/schemas/GoalEventDto'
        - $ref: '#/components/schemas/EjectedEventDto'
        - $ref: '#/components/schemas/FoulEventDto'