Avokkado Play Events Controller REST API Design v2

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:
    post:
      tags: [Events]
      summary: Create event
      requestBody: { $ref: '#/components/requestBodies/CreateEventDto' }
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/EventDto' }
    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/{id}:
    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' }
    
    put:
      tags: [Events]
      summary: Update card event
      parameters:
        - $ref: '#/components/parameters/EventId'
      requestBody: { $ref: '#/components/requestBodies/CreateEventDto' }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CardEventDto' }

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

components:
  parameters:
    EventId:
      name: id
      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:
    CreateEventDto:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateEventDto'

  schemas:
    EventType:
      type: string
      enum: [card, goal, ejected, foul]
      description: "Available event types"
      
    BaseEventDto:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
          example: 42
        time:
          type: string
          format: date-time
          example: '2025-07-03T17:54:17.401Z'
        teamId:
          type: integer
        matchId:
          type: integer
          example: 99
        eventType:
          $ref: '#/components/schemas/EventType'
    
    CardEventDto:
      type: object
      properties:
        playerId:
          type: integer
        type:
          type: integer
              
    GoalEventDto:
      type: object
      properties:
        scorerId:
          type: integer
        assisterId:
          type: integer
          nullable: true
              
    EjectedEventDto:
      type: object
      properties:
        playerId:
          type: integer
        missingMatches:
          type: integer
          minimum: 0
              
    FoulEventDto:
      type: object
      properties:
        playerId:
          type: integer
        duration:
          type: integer
          description: Penalty box time (minutes)
          
    CreateEventDto:
      allOf:
        - $ref: '#/components/schemas/BaseEventDto'
        
        - type: object
          properties:
            card:
              $ref: '#/components/schemas/CardEventDto'
            goal:
              $ref: '#/components/schemas/GoalEventDto'
            ejected:
              $ref: '#/components/schemas/EjectedEventDto'
            foul:
              $ref: '#/components/schemas/FoulEventDto'
              
    EventDto:
      allOf:
        - $ref: '#/components/schemas/BaseEventDto'
        
        - type: object
          properties:
            card:
              $ref: '#/components/schemas/CardEventDto'
            goal:
              $ref: '#/components/schemas/GoalEventDto'
            ejected:
              $ref: '#/components/schemas/EjectedEventDto'
            foul:
              $ref: '#/components/schemas/FoulEventDto'