openapi: 3.0.0
info:
  title: Aquarius REST API
  description: |-
    API for retrieving information from the regatta management software Aquarius.
    The API is available on the info point port using the prefix /api/v1/. 
    To get a list of events, request them from http://host:port/api/v1/events.
  contact:
    name: Steffen Christgau
    email: mail@s14u.de
  version: 1.0.1
tags:
  - name: event
    description: information on regattas/events
  - name: races
    description: information on offered races for a given regatta
  - name: schedule
    description: racing schedule information
  - name: athletes
    description: information on the participating athletes
  - name: entries
    description: some des
paths:
  /events:
    get:
      tags:
        - event
      summary: list of all events
      description: Return a list of all events, i.e. regattas, in the database, sorted by event start date
      operationId: fetchEventList
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:              
                  $ref: '#/components/schemas/Event'
  /event/{event_id}:
    get:
      tags:
        - event 
      summary: return a single event
      description: Information of a single event/regatta
      operationId: fetchSingleEvent
      parameters:
        - name: event_id
          in: path
          description: ID of event to return
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Sucessful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
  /event/{event_id}/races:
    get:
      tags:
        - races
      summary: return offered races for the event
      description: Return the list of offered races for the given event in the offer order
      operationId: fetchEventRaces
      parameters:
        - name: event_id
          in: path
          description: ID of the event for which to get the offered races
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Sucessful operation
          content:
            application/json:
              schema:
                type: array
                items:                
                  $ref: '#/components/schemas/Race'
  /race/{race_id}:
    get:
      tags:
        - races
      summary: return offered races for the event
      description: Return the list of offered races for the given event in the offer order
      operationId: fetchRace
      parameters:
        - name: race_id
          in: path
          description: ID of the event for which to get the offered races
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Sucessful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Race'
  /event/{event_id}/schedule:
    get:
      tags:
        - schedule
      operationId: fetchEventSchedule
      parameters:
        - name: event_id
          in: path
          description: ID of the event of 
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ScheduleItem'
  /race/{race_id}/schedule:
    get:
      tags:
        - schedule
      operationId: fetchRaceSchedule
      parameters:
        - name: race_id
          in: path
          description: ID of the race to fetch the schedule for.
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ScheduleItem'
  /event/{event_id}/athletes:
    get:
      tags:
        - athletes
      operationId: fetchEventAthletes
      parameters:
        - name: event_id
          in: path
          description: ID of the event
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AthleteWithClub'
  /event/{event_id}/athlete/{athlete_id}:
    get:
      tags:
        - athletes
      operationId: fetchEventAthlete
      parameters:
        - name: event_id
          in: path
          description: ID of the event
          required: true
          schema:
            type: integer
            format: int64
        - name: athlete_id
          in: path
          description: ID of the athlete
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventAthleteItemWithRaces'
  /race/{race_id}/entries:
    get:
      tags:
        - entries
      summary: return entries for race
      description: Get all entries of the given race
      operationId: fetchRaceEntries
      parameters:
        - name: race_id
          in: path
          description: ID of the athlete
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Entry'
  /entry/{entry_id}:
    get:
      tags:
        - entries
      summary: return startlist and results along with according crew for a given entry
      description: bla
      operationId: fetchEntry
      parameters:
        - name: entry_id
          in: path
          description: ID of the entry
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FullCompetition'
  /comp/{comp_id}:
    get:
      tags:
        - competiton
      summary: get full info about competition
      description: return basic information about a competition, splits, the startlist and the results of each competitor
      operationId: fetchCompetition
      parameters:
        - name: comp_id
          in: path
          description: ID of the competition
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FullCompetition'
components:
  schemas:
    Event:
      type: object
      properties:
        id:
          type: integer
          format: int32
          example: 1
        title:
          type: string
          example: "Example Regatta"
        sub_title:
          type: string
        start_date:
          type: string
          example: "2023-01-01"
        end_date:
          type: string
          example: "2023-01-02"
        venue:
          type: string
          example: "Lago Examplos"
        venue_nation:
          type: string
          description: "ISO 3166-3 code"
          example: "ESP"
    Race:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 123
        race_number:
          type: string
          example: "M1"
        short_label:
          type: string
          example: "SM 1x A"
        long_label:
          type: string
          example: "Männer-Einer A"
        comment:
          type: string
        distance:
          type: integer
          example: 2000
        is_lightweight:
          type: boolean
          example: false
        split_count:
          type: integer
          example: 3
        cancelled:
          type: boolean
          example: false
        prize:
          type: string
          example: "Wanderpokal"
    ScheduleItem:
      type: object
      properties:
        id:
          type: integer
          example: 345
        race_id:
          type: integer
          example: 123
        heat_number:
          type: integer
          example: 1
        round_code:
          type: string
          example: "V"
        round:
          type: integer
          example: 4
        label:
          type: string
          example: "A"
        group_value:
          type: integer
          example: 0
        datetime:
          type: string
          example: "2023-04-18T16:00:00"
          description: "Schedule start time of the competition, local time"
        state:
          type: integer
          example: 3
        number:
          type: integer
          example: 1
        is_dummy:
          type: boolean
          example: false
        is_cancelled:
          type: boolean
          example: true
    Entry:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 6789
        bib_prefix:
          type: string
          example: A
        bib:
          type: integer
          format: int64
          example: 38
        cancel_state:
          type: integer
          format: int64
          example: 0
        is_late:
          type: boolean
          example: false
        is_team:
          type: boolean
          example: false
        is_club_multi_noc:
          type: boolean
          example: false
        is_crew_multi_noc:
          type: boolean
          example: false
        labels:
          type: object
          properties:
            long:
              type: string
              example: "Ruder-Club Beispiel e.V."
            short:
              type: string
              example: "RC Beispiel"
    AthleteWithClub:
      allOf:
        - $ref: '#/components/schemas/Athlete'
        - type: object
          properties:
            club_id:
              type: integer
              example: 36987
            club_name:
              type: string
              example: "Ruder-Club Beispiel e.V."
    Athlete:
      type: object
      properties:
        id:
          type: integer
          example: 564789
        lastname:
          type: string
          example: "Row"
        firstname:
          type: string
          example: "John"
        yob:
          type: integer
          example: 1970
        sex:
          type: string
          example: "M"
    EventAthleteItemWithRaces:
      allOf: 
        - $ref: '#/components/schemas/AthleteWithClub'
        - type: object
          properties:
            races:
              type: array
              items:
                type: object
                properties:
                  race_id:
                    type: integer
                    example: 123
                  race_number:
                    type: string
                    example: "M1"
                  entry_id:
                    type: integer
                    example: 6789
    FullCompetition:
      allOf:
        - $ref: '#/components/schemas/ScheduleItem'
        - type: object
          properties:
            splits:
              type: array
              items:
                type: integer
              example: [0, 500, 1000, 1500, 2000]
              description: Array of the distances at which (split) times/results are recorded. Always includes the start, i.e. 0m, and the distance of the competition/race.
        - type: object
          properties:
            entries:
              type: array
              items:
                $ref: '#/components/schemas/EntryWithLaneCrewAndResult'
    EntryWithLaneCrewAndResult:
      allOf:
        - $ref: '#/components/schemas/Entry'
        - type: object
          properties:
            lane:
              type: integer
              example: 3
            has_yellow_card:
              type: boolean
              example: true
            crew:
              type: array
              items:
                $ref: '#/components/schemas/CrewMember'
            results:
              type: array
              items:
                $ref: '#/components/schemas/Result'
    CrewMember:
      type: object
      properties:
        position:
          type: integer
          example: 1
        is_cox:
          type: boolean
          example: false
        athlete:
          $ref: '#/components/schemas/AthleteWithClub'
    Result:
      type: object
      required: [ 'split_number', 'rank', 'display', 'time', 'delta' ]
      properties:
        split_number:
          type: integer
          example: 64
          description: Number of the result's split. One-based index in the splits array of the FullCompetition. However, always 64 for the last entry in this array, i.e. the result at the finish.
        rank:
          type: integer
          example: 2
        display:
          type: string
          description: textual respresentation of the result
          example: "7:32.16"
        time:
          type: integer
          description: Time in milliseconds
          example: 452160
        delta:
          type: integer
          description: time the competitor arrived after the first one
          example: 1593
        time_of_day:
          type: string
          description: Time of the day, the result is associated with; only returned for the start result (i.e. split number 0)
          example: "12:34:45.678"