api.yaml

openapi: 3.0.3

info:
  title: Race Day API
  version: "1.0"
  description: A REST API for accessing data stored in Race Day.


paths:

  /access_token:

    get:
      operationId: accessTokenGet

      summary: Provides a new access token. Access tokens expire after a configurable amount of time (24 hours by
        default). Note also that access tokens are tied to your IP address, so you will need to acquire a new access
        token if you use a different host or connect via a different means.

      parameters:
        - name: Username
          in: header
          required: true
          schema:
            type: string
        - name: Password
          in: header
          required: true
          schema:
            type: string

      responses:
        "200":
          description: Successful response.
          content:
            application/json:
              schema:
                type: string
                format: uuid
        "401":
          description: Invalid credentials.
      
      tags:
        - Protected

  /broadcast:

    delete:
      operationId: broadcastDelete

      summary: Deletes a broadcast.

      parameters:
        - $ref: "#/components/parameters/AccessTokenParam"
        - name: id
          in: query
          required: true
          schema:
            type: string
            format: uuid

      responses:
        "200":
          description: Successful response.
        "403":
          description: Unauthorized.
        "404":
          description: Broadcast not found.
      
      tags:
        - Protected

    post:
      operationId: broadcastPost

      summary: Creates a new broadcast.

      parameters:
        - $ref: "#/components/parameters/AccessTokenParam"
      
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UnsavedBroadcast"

      responses:
        "200":
          description: Successful response indicating the ID of the new broadcast.
          content:
            application/json:
              schema:
                type: string
                format: uuid
        "403":
          description: Unauthorized.
      
      tags:
        - Protected

    put:
      operationId: broadcastPut

      summary: Updates a broadcast.

      parameters:
        - $ref: "#/components/parameters/AccessTokenParam"

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Broadcast"

      responses:
        "200":
          description: Successful response.
        "403":
          description: Unauthorized.
        "404":
          description: Broadcast or referenced event not found.
      
      tags:
        - Protected

  /broadcasts:

    delete:
      operationId: broadcastsDelete

      summary: Deletes broadcasts.

      parameters:
        - $ref: "#/components/parameters/AccessTokenParam"
        - name: ids
          in: query
          description: The IDs of the broadcasts to delete.
          required: true
          schema:
            type: array
            items:
              type: string
              format: uuid

      responses:
        "200":
          description: Successful response.
        "403":
          description: Unauthorized.
        "404":
          description: One or more broadcasts not found.
      
      tags:
        - Protected

    get:
      operationId: broadcastsGet

      summary: Retrieves broadcasts per the specified criteria. All parameters are optional.

      parameters:
        - name: event_id
          in: query
          description: An ID of an event for which to retrieve broadcasts.
          schema:
            type: string
            format: uuid
        - name: event_start
          in: query
          description: A UNIX timestamp indicating a particular date on which returned broadcasts must start.
          schema:
            type: number
            format: int64
        - name: include_all_after
          in: query
          description: Indicates that the event_start parameter should be the earliest that returned broadcasts must
            start, but any broadcast that airs after that time will also be included.
          schema:
            type: boolean
            default: false

      responses:
        "200":
          description: Successful response.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Broadcast"
        "404":
          description: Event not found.
      
      tags:
        - Query
    
    post:
      operationId: broadcastsPost

      summary: Creates new broadcasts.

      parameters:
        - $ref: "#/components/parameters/AccessTokenParam"

      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/UnsavedBroadcast"

      responses:
        "200":
          description: Successful response indicating the IDs of the new broadcasts.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  format: uuid
        "403":
          description: Unauthorized.
      
      tags:
        - Protected

    put:
      operationId: broadcastsPut

      summary: Updates broadcasts.

      parameters:
        - $ref: "#/components/parameters/AccessTokenParam"

      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/Broadcast"

      responses:
        "200":
          description: Successful response.
        "403":
          description: Unauthorized.
        "404":
          description: One or more referenced events not found.
      
      tags:
        - Protected

  /event:

    delete:
      operationId: eventDelete

      summary: Deletes an event.

      parameters:
        - $ref: "#/components/parameters/AccessTokenParam"
        - name: id
          in: query
          description: The ID of the event to delete.
          required: true
          schema:
            type: string
            format: uuid

      responses:
        "200":
          description: Successful response.
        "403":
          description: Unauthorized.
        "404":
          description: Event not found.
      
      tags:
        - Protected

    post:
      operationId: eventPost

      summary: Creates a new event.

      parameters:
        - $ref: "#/components/parameters/AccessTokenParam"

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UnsavedEvent"

      responses:
        "200":
          description: Successful response indicating the ID of the new event.
          content:
            application/json:
              schema:
                type: string
                format: uuid
        "403":
          description: Unauthorized.
      
      tags:
        - Protected

    put:
      operationId: eventPut

      summary: Updates an event.

      parameters:
        - $ref:  "#/components/parameters/AccessTokenParam"

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Event"

      responses:
        "200":
          description: Successful response.
        "403":
          description: Unauthorized.
        "404":
          description: Event not found.
      
      tags:
        - Protected

  /events:

    get:
      operationId: eventsGet

      summary: Retrieves events in the database for the specified date or dates.

      parameters:
        - name: window_start
          in: query
          description: A UNIX timestamp indicating a particular date on which returned events must start.
          required: true
          schema:
            type: number
            format: int64
        - name: window_end
          in: query
          description: An optional UNIX timestamp indicating the end of a window in which returned events must start,
            where `window_start` indicates the beginning of the window. If not specified, only events that start on the
            date indicated by `window_start` will be returned. If -1 is specified, all events that occur on or after the
            date indicated by `window_start` are returned.
          schema:
            type: number
            format: int64
        - name: time_zone
          in: query
          description: The time zone to take into account when querying for events. If not specified, UTC is used.
          schema:
            type: string

      responses:
        "200":
          description: Successful response.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Event"
      
      tags:
        - Query
  
  /export:

    get:
      operationId: exportGet

      summary: Exports data using the specified format. Note that the window_start, window_end, and time_zone parameters
        may be ignored by some export types.

      parameters:
        - name: export_type
          in: query
          description: The type of export to be created. Use the GET /export_types API to get a list of possible types.
          required: true
          schema:
            type: string
        - name: window_start
          in: query
          description: A UNIX timestamp indicating a particular date on which exported events must start.
          required: true
          schema:
            type: number
            format: int64
        - name: window_end
          in: query
          description: An optional UNIX timestamp indicating the end of a window in which exported events must start,
            where `window_start` indicates the beginning of the window. If not specified, only events that start on the
            date indicated by `window_start` will be exported. If -1 is specified, all events that occur on or after the
            date indicated by `window_start` are exported.
          schema:
            type: number
            format: int64
        - name: time_zone
          in: query
          description: The time zone to take into account when querying for events. If not specified, UTC is used.
          schema:
            type: string
      
      responses:
        "200":
          description: Successful response.
          content:
            application/*s:
              schema:
                type: string
                format: binary
        "404":
          description: Export type not found.
      
      tags:
        - Query
  
  /export_types:

    get:
      operationId: exportTypesGet

      summary: Retrieves the names of the available export types.

      responses:
        "200":
          description: Successful response.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
      
      tags:
        - Query
  
  /langs:

    get:
      operationId: langsGet

      summary: Retrieves the languages defined in the system.

      responses:
        "200":
          description: Successful response.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Lang"
      
      tags:
        - Query

  /location:

    post:
      operationId: locationPost

      summary: Creates a new location.

      parameters:
        - $ref: "#/components/parameters/AccessTokenParam"

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UnsavedLocation"

      responses:
        "200":
          description: Successful response indicating the ID of the new location.
          content:
            application/json:
              schema:
                type: string
                format: uuid
        "403":
          description: Unauthorized.
      
      tags:
        - Protected

    put:
      operationId: locationPut

      summary: Updates a location.

      parameters:
        - $ref: "#/components/parameters/AccessTokenParam"
      
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Location"

      responses:
        "200":
          description: Successful response.
        "403":
          description: Unauthorized.
        "404":
          description: Location not found.
      
      tags:
        - Protected

  /locations:

    get:
      operationId: locationsGet

      summary: Retrieves the locations currently defined in the system.

      responses:
        "200":
          description: Successful response.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Location"
      
      tags:
        - Query

  /series:

    get:
      operationId: seriesGet

      summary: Retrieves the series currently defined in the system.

      responses:
        "200":
          description: Successful response.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Series"
      
      tags:
        - Query

    post:
      operationId: seriesPost

      summary: Creates a new series.

      parameters:
        - $ref: "#/components/parameters/AccessTokenParam"

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UnsavedSeries"

      responses:
        "200":
          description: Successful response indicating the ID of the new series.
          content:
            application/json:
              schema:
                type: string
                format: uuid
        "403":
          description: Unauthorized.
      
      tags:
        - Protected

    put:
      operationId: seriesPut

      summary: Updates a series.

      parameters:
        - $ref: "#/components/parameters/AccessTokenParam"

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Series"

      responses:
        "200":
          description: Successful response.
        "403":
          description: Unauthorized.
        "404":
          description: Series not found.
      
      tags:
        - Protected


components:

  parameters:

    AccessTokenParam:
      in: header
      name: AccessToken
      description: The ID of the access token by which protected resources can be accessed. Acquired via the GET
        /access_token API.
      schema:
        type: string
        format: uuid
      required: true


  schemas:

    Broadcast:
      type: object
      properties:
        id:
          description: The ID of the broadcast.
          type: string
          format: uuid
        # Really should be ref to BroadcastType but can't because of bug. Make sure to update all definitions in here
        # when you update!
        type_:
          description: The type of a broadcast.
          type: string
          enum:
            - Cable
            - Facebook
            - F1_TV
            - Motorsport_tv
            - MotorTrend
            - Other
            - YouTube
        event:
          $ref: "#/components/schemas/Event"
        lang_ids:
          type: array
          items:
            type: string
        description:
          description: A description of the broadcast.
          type: string
        url:
          description: A URL providing a way to watch the broadcast.
          type: string
        geoblocked:
          description: Whether or not the broadcast is geoblocked.
          type: boolean
        paid:
          description: Whether or not the broadcast requires a paid account
          type: boolean
      required:
        - id
        - type_
        - event
        - lang_ids
    
    # Unable to reference due to bug in Swagger Codegen (https://github.com/swagger-api/swagger-codegen/issues/7763), so
    # the properties which reference this 
    BroadcastType:
      description: The type of a broadcast.
      type: string
      enum:
        - Cable
        - Facebook
        - F1_TV
        - Motorsport_tv
        - MotorTrend
        - Other
        - YouTube

    Event:
      type: object
      properties:
        id:
          description: The ID of the event.
          type: string
          format: uuid
        name:
          description: The name of the event.
          type: string
        start:
          description: A UNIX timestamp indicating when the event starts.
          type: number
          format: int64
        description:
          description: A description of the event.
          type: string
        location:
          $ref: "#/components/schemas/Location"
        series:
          $ref: "#/components/schemas/Series"
      required:
        - id
        - name
        - start
    
    Lang:
      type: object
      properties:
        id:
          description: The name of the language.
          type: string
        html_code:
          description: The HTML character entity that can be used to display the associated flag of the language.
          type: string
        country_code:
          description: The two-letter country code associated with this language.
          type: string
        priority_listing:
          description: Whether or not this language should be highlighted among a list of languages.
          type: boolean
      required:
        - id
        - html_code
        - country_code
        - priority_listing

    Location:
      type: object
      properties:
        id:
          description: The ID of the location.
          type: string
          format: uuid
        name:
          description: The name of the location.
          type: string
        description:
          description: A description of the location.
          type: string
      required:
        - id
        - name

    Series:
      type: object
      properties:
        id:
          description: The ID of the series.
          type: string
          format: uuid
        name:
          description: The name of the series.
          type: string
        description:
          description: A description of the series.
          type: string
      required:
        - id
        - name

    SystemUser:
      type: object
      properties:
        id:
          description: The ID of the user.
          type: string
        first_name:
          description: The first name of the user.
          type: string
        last_name:
          description: The last name of the user.
          type: string
        email:
          description: The e-mail address of the user.
          type: string
        when_created:
          description: A UNIX timestamp indicating when this user was created.
          type: integer
        who_created:
          description: The ID of the user that created this user.
          type: string
        when_updated:
          description: A UNIX timestamp indicating when this user was last updated.
          type: integer
        who_updated:
          description: The ID of the last user to update this user.
          type: string
        enabled:
          description: Whether or not this user is enabled and can login to the system.s
          type: boolean
      required:
        - id
        - when_created
        - enabled

    UnsavedBroadcast:
      type: object
      properties:
        # Really should be ref to BroadcastType but can't because of bug. Make sure to update all definitions in here
        # when you update!
        type_:
          description: The type of a broadcast.
          type: string
          enum:
            - Cable
            - Facebook
            - F1_TV
            - Motorsport_tv
            - MotorTrend
            - Other
            - YouTube
        event_id:
          description: The ID of the event associated with this broadcast.
          type: string
          format: uuid
        lang_ids:
          type: array
          items:
            type: string
        description:
          description: A description of the broadcast.
          type: string
        url:
          description: A URL providing a way to watch the broadcast.
          type: string
        geoblocked:
          description: Whether or not the broadcast is geoblocked.
          type: boolean
        paid:
          description: Whether or not the broadcast requires a paid account
          type: boolean
      required:
        - type_
        - event_id
        - lang_ids

    UnsavedEvent:
      type: object
      properties:
        name:
          description: The name of the event.
          type: string
        start:
          description: A UNIX timestamp indicating when the event starts.
          type: number
          format: int64
        description:
          description: A description of the event.
          type: string
        location:
          $ref: "#/components/schemas/Location"
        series:
          $ref: "#/components/schemas/Series"
      required:
        - name
        - start

    UnsavedLocation:
      type: object
      properties:
        name:
          description: The name of the location.
          type: string
        description:
          description: A description of the location.
          type: string
      required:
        - name

    UnsavedSeries:
      type: object
      properties:
        name:
          description: The name of the series.
          type: string
        description:
          description: A description of the series.
          type: string
      required:
        - name