spec.yml

---
openapi: 3.1.0
info:
  title: A brand new Formula API
  summary: Todo
  description: Todo
  version: 0.0.1
  contact:
    name: Thibault Cheneviere
    email: thibault.chene23@gmail.com
    url: https://thibault-cne.fr

tags: 
  - name: drivers
    description: Informations on drivers.
  - name: current
    description: Informations on the current season.
  - name: standings
    description: Informations on the standings, drivers or constructors.
  - name: constructors
    description: Informations on constructors.
  - name: seasons
    description: Informations on seasons currently supported.
  
paths:
  /api/status:
    get:
      description: Returns the current status of the API.
      responses:
        '200':
          description: The API is up and running.
          content: 
            application/json: 
              schema:
                $ref: '#/components/schemas/Status'
        '503':
          description: The API is not available.
          content: 
            application/json: 
              schema: 
                $ref: '#/components/schemas/Status'
  /api/{series}/seasons:
    parameters: 
      - $ref: '#/components/parameters/Series'
    get:
      tags:
        - seasons
      description: Retrieve informations on currently supported seasons.
      parameters: 
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/NbPerPage'
        - $ref: '#/components/parameters/SeasonsDriverRef'
        - $ref: '#/components/parameters/SeasonsDriverNumber'
        - $ref: '#/components/parameters/ConstructorRef'
        - $ref: '#/components/parameters/CircuitRef'
        - $ref: '#/components/parameters/SeasonsGrid'
        - $ref: '#/components/parameters/SeasonsResult'
      responses:
        '200':
          $ref: '#/components/responses/SeasonsResponse'

  /api/{series}/constructors:
    parameters: 
      - $ref: '#/components/parameters/Series'
    get:
      tags: 
        - constructors
      description: Retrieve information on constructors.
      parameters: 
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/NbPerPage'
        - $ref: '#/components/parameters/DriverRef'
        - $ref: '#/components/parameters/DriverNumber'
        - $ref: '#/components/parameters/ConstructorRef'
        - $ref: '#/components/parameters/CircuitRef'
        - $ref: '#/components/parameters/Grid'
        - $ref: '#/components/parameters/Result'
      responses: 
        '200':
          $ref: '#/components/responses/ConstructorsResponse'
  /api/{series}/{year}/constructors:
    parameters: 
      - $ref: '#/components/parameters/Series'
      - $ref: '#/components/parameters/Year'
    get:
      tags: 
        - constructors
      description: Retrieve information on constructors of a specific season.
      parameters: 
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/NbPerPage'
        - $ref: '#/components/parameters/DriverRef'
        - $ref: '#/components/parameters/DriverNumber'
        - $ref: '#/components/parameters/ConstructorRef'
        - $ref: '#/components/parameters/CircuitRef'
        - $ref: '#/components/parameters/Grid'
        - $ref: '#/components/parameters/Result'
      responses: 
        '200':
          $ref: '#/components/responses/ConstructorsResponse'
  /api/{series}/{year}/{round}/constructors:
    parameters: 
      - $ref: '#/components/parameters/Series'
      - $ref: '#/components/parameters/Year'
      - $ref: '#/components/parameters/Round'
    get:
      tags: 
        - constructors
      description: Retrieve information on constructors of a specific round of a season.
      parameters: 
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/NbPerPage'
        - $ref: '#/components/parameters/DriverRef'
        - $ref: '#/components/parameters/DriverNumber'
        - $ref: '#/components/parameters/ConstructorRef'
        - $ref: '#/components/parameters/CircuitRef'
        - $ref: '#/components/parameters/Grid'
        - $ref: '#/components/parameters/Result'
      responses: 
        '200':
          $ref: '#/components/responses/ConstructorsResponse'
  /api/{series}/current/constructors:
    parameters: 
      - $ref: '#/components/parameters/Series'
    get:
      tags: 
        - constructors
        - current
      description: Retrieve information on constructors of the current season.
      parameters: 
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/NbPerPage'
        - $ref: '#/components/parameters/DriverRef'
        - $ref: '#/components/parameters/DriverNumber'
        - $ref: '#/components/parameters/ConstructorRef'
        - $ref: '#/components/parameters/CircuitRef'
        - $ref: '#/components/parameters/Grid'
        - $ref: '#/components/parameters/Result'
      responses: 
        '200':
          $ref: '#/components/responses/ConstructorsResponse'
  /api/{series}/current/{round}/constructors:
    parameters: 
      - $ref: '#/components/parameters/Series'
      - $ref: '#/components/parameters/Round'
    get:
      tags: 
        - constructors
        - current
      description: Retrieve information on constructors of a specific round of the current season.
      parameters: 
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/NbPerPage'
        - $ref: '#/components/parameters/DriverRef'
        - $ref: '#/components/parameters/DriverNumber'
        - $ref: '#/components/parameters/ConstructorRef'
        - $ref: '#/components/parameters/CircuitRef'
        - $ref: '#/components/parameters/Grid'
        - $ref: '#/components/parameters/Result'
      responses: 
        '200':
          $ref: '#/components/responses/ConstructorsResponse'


  /api/{series}/drivers:
    parameters: 
      - $ref: '#/components/parameters/Series'
    get:
      tags: 
        - drivers
      description: Retrieve information on drivers.
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/NbPerPage'
        - $ref: '#/components/parameters/DriverNumber'
        - $ref: '#/components/parameters/DriverRef'
        - $ref: '#/components/parameters/ConstructorRef'
        - $ref: '#/components/parameters/CircuitRef'
        - $ref: '#/components/parameters/Grid'
        - $ref: '#/components/parameters/Result'
      responses: 
        '200':
          $ref: '#/components/responses/DriversResponse'
  /api/{series}/{year}/drivers:
    parameters: 
      - $ref: '#/components/parameters/Series'
      - $ref: '#/components/parameters/Year'
    get:
      tags: 
        - drivers
      description: Retrieve information on drivers of a specific season.
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/NbPerPage'
        - $ref: '#/components/parameters/DriverNumber'
        - $ref: '#/components/parameters/DriverRef'
        - $ref: '#/components/parameters/ConstructorRef'
        - $ref: '#/components/parameters/CircuitRef'
        - $ref: '#/components/parameters/Grid'
        - $ref: '#/components/parameters/Result'
      responses: 
        '200':
          $ref: '#/components/responses/DriversResponse'
  /api/{series}/{year}/{round}/drivers:
    parameters: 
      - $ref: '#/components/parameters/Series'
      - $ref: '#/components/parameters/Year'
      - $ref: '#/components/parameters/Round'
    get:
      tags: 
        - drivers
      description: Retrieve information on drivers of a specific round of a season.
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/NbPerPage'
        - $ref: '#/components/parameters/DriverNumber'
        - $ref: '#/components/parameters/DriverRef'
        - $ref: '#/components/parameters/ConstructorRef'
        - $ref: '#/components/parameters/CircuitRef'
        - $ref: '#/components/parameters/Grid'
        - $ref: '#/components/parameters/Result'
      responses: 
        '200':
          $ref: '#/components/responses/DriversResponse'
  /api/{series}/current/drivers:
    parameters: 
      - $ref: '#/components/parameters/Series'
    get:
      tags:
        - drivers
        - current
      description: Retrieve information on drivers of the current season.
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/NbPerPage'
        - $ref: '#/components/parameters/DriverNumber'
        - $ref: '#/components/parameters/DriverRef'
        - $ref: '#/components/parameters/ConstructorRef'
        - $ref: '#/components/parameters/CircuitRef'
        - $ref: '#/components/parameters/Grid'
        - $ref: '#/components/parameters/Result'
      responses: 
        '200':
          $ref: '#/components/responses/DriversResponse'
  /api/{series}/current/{round}/drivers:
    parameters: 
      - $ref: '#/components/parameters/Series'
      - $ref: '#/components/parameters/Round'
    get:
      tags: 
        - drivers
        - current
      description: Retrieve information on drivers of a specific round of the current season.
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/NbPerPage'
        - $ref: '#/components/parameters/DriverNumber'
        - $ref: '#/components/parameters/DriverRef'
        - $ref: '#/components/parameters/ConstructorRef'
        - $ref: '#/components/parameters/CircuitRef'
        - $ref: '#/components/parameters/Grid'
        - $ref: '#/components/parameters/Result'
      responses: 
        '200':
          $ref: '#/components/responses/DriversResponse'

  /api/{series}/{year}/standings/constructors:
    get:
      tags:
        - standings
      description: Retrieve the constructors standings of a specific season.
      parameters: 
        - $ref: '#/components/parameters/Series'
        - $ref: '#/components/parameters/Year'
        - $ref: '#/components/parameters/ConstructorRef'
        - $ref: '#/components/parameters/Result'
      responses: 
        '200':
          $ref: '#/components/responses/ConstructorsStandingsResponse'
  /api/{series}/{year}/standings/drivers:
    get:
      tags:
        - standings
      description: Retrieve the drivers standings of a specific season.
      parameters: 
        - $ref: '#/components/parameters/Series'
        - $ref: '#/components/parameters/Year'
        - $ref: '#/components/parameters/DriverRef'
        - $ref: '#/components/parameters/Result'
      responses: 
        '200':
          $ref: '#/components/responses/DriversStandingsResponse'
  /api/{series}/{year}/{round}/standings/constructors:
    get:
      tags:
        - standings
      description: Retrieve the constructors standings of a specific round of a season.
      parameters: 
        - $ref: '#/components/parameters/Series'
        - $ref: '#/components/parameters/Year'
        - $ref: '#/components/parameters/Round'
        - $ref: '#/components/parameters/ConstructorRef'
        - $ref: '#/components/parameters/Result'
      responses: 
        '200':
          $ref: '#/components/responses/ConstructorsStandingsResponse'
  /api/{series}/{year}/{round}/standings/drivers:
    get:
      tags:
        - standings
      description: Retrieve the drivers standings of a specific round of a season.
      parameters: 
        - $ref: '#/components/parameters/Series'
        - $ref: '#/components/parameters/Year'
        - $ref: '#/components/parameters/Round'
        - $ref: '#/components/parameters/DriverRef'
        - $ref: '#/components/parameters/Result'
      responses: 
        '200':
          $ref: '#/components/responses/DriversStandingsResponse'
  /api/{series}/current/standings/constructors:
    get:
      tags:
        - standings
        - current
      description: Retrieve the constructors standings of the current season.
      parameters: 
        - $ref: '#/components/parameters/Series'
        - $ref: '#/components/parameters/ConstructorRef'
        - $ref: '#/components/parameters/Result'
      responses: 
        '200':
          $ref: '#/components/responses/ConstructorsStandingsResponse'
  /api/{series}/current/standings/drivers:
    get:
      tags:
        - standings
        - current
      description: Retrieve the drivers standings of the current season.
      parameters: 
        - $ref: '#/components/parameters/Series'
        - $ref: '#/components/parameters/DriverRef'
        - $ref: '#/components/parameters/Result'
      responses: 
        '200':
          $ref: '#/components/responses/DriversStandingsResponse'


components:
  parameters:
    SeasonsDriverNumber:
      name: driver_number
      in: query
      description: The unique number of a driver.
      schema:
        type: integer
        format: int32
        examples:
          - 1
          - 10
      required: false
    SeasonsDriverRef:
      name: driver_ref
      in: query
      description: The reference of a driver (usualy the family name in lowercase).
      schema:
        type: string
        examples:
        - alonso
        - hamilton
      required: false
    DriverNumber:
      name: driver_number
      in: query
      description: The unique number of a driver. This parameter **must** be used alone.
      schema:
        type: integer
        format: int32
        examples:
          - 1
          - 10
      required: false
    DriverRef:
      name: driver_ref
      in: query
      description: The reference of a driver (usualy the family name in lowercase). This parameter **must** be used alone.
      schema:
        type: string
        examples:
        - alonso
        - hamilton
      required: false
    ConstructorRef:
      name: constructor
      in: query
      description: A constructor ref. It will retrieve all drivers who has run for this constructor or the specific constructor.
      schema:
        type: string
        examples:
          - renault
          - redbull
      required: false
    CircuitRef:
      name: circuit
      in: query
      description: A circuit ref. It will retrieve all drivers or constructors who has run on this specific circuit.
      schema:
        type: string
        examples:
          - monza
          - monaco
      required: false
    Grid:
      name: grid
      in: query
      description: A specific grid position. It will retrieve all drivers or constructors who has started a Grand Prix from this specific grid position.
      schema:
        type: integer
        format: int32
        examples:
          - 1
          - 10
      required: false
    Result:
      name: result
      in: query
      description: A specific result position. It will retrieve all drivers or constructors who has finished a Grand Prix at this position.
      schema:
        type: integer
        format: int32
        examples:
          - 1
          - 10
      required: false
    SeasonsGrid:
      name: grid
      in: query
      description: A specific grid position. **It must be used with either a driver reference or number or a constructor name.** It will retrieve all seasons when the drivers or constructors have started a Grand Prix from this specific grid position.
      schema:
        type: integer
        format: int32
        examples:
          - 1
          - 10
      required: false
    SeasonsResult:
      name: result
      in: query
      description: A specific result position. **It must be used with either a driver reference or number or a constructor name.** It will retrieve all seasons when the drivers or constructors have finished a Grand Prix at this position.
      schema:
        type: integer
        format: int32
        examples:
          - 1
          - 10
      required: false
    Year:
      name: year
      in: path
      required: true
      description: A season year.
      schema:
        type: integer
        format: int32
        examples:
          - 2023
          - 2022
    Round:
      name: round
      in: path
      required: true
      description: A round of a championship season.
      schema:
        type: integer
        format: int32
        examples:
          - 1
          - 17
    Series:
      name: series
      in: path
      required: true
      description: A championship series.
      schema:
        $ref: '#/components/schemas/Series'
    Page:
      name: page
      in: query
      description: The page to retrieve. `-1` will retrieve the last page. The page system is indexed in range `1..`. The default value is `1`.
      schema: 
        type: integer
        format: int32
        examples:
          - 1
          - 2
          - -1
        default: 1
    NbPerPage:
      name: limit
      in: query
      description: The limit of items to retrieve per `page`. The value `-1` is used to retrieve all elements in the page. The default value is `30`.
      schema: 
        type: integer
        format: int32
        examples:
          - 10
          - -1
        default: 30
  responses:
    StandingsResponse:
      description: The queried standings.
      content:
        application/json: 
          schema: 
            $ref: '#/components/schemas/StandingsResponse'
    ConstructorsStandingsResponse:
      description: The queried standings.
      content:
        application/json: 
          schema: 
            $ref: '#/components/schemas/ConstructorsStandingsResponse'
    DriversStandingsResponse:
      description: The queried standings.
      content:
        application/json: 
          schema: 
            $ref: '#/components/schemas/DriversStandingsResponse'
    ConstructorsResponse:
      description: The queried constructors.
      content:
        application/json: 
          schema:
            $ref: '#/components/schemas/ConstructorsResponse'
    DriversResponse:
      description: The queried drivers.
      content:
        application/json: 
          schema:
            $ref: '#/components/schemas/DriversResponse'
    SeasonsResponse:
      description: The queried seasons.
      content:
        application/json: 
          schema:
            $ref: '#/components/schemas/SeasonsResponse'
  schemas:
    StandingsResponse:
      allOf: 
        - $ref: '#/components/schemas/DefaultResponse'
        - type: object
          required: 
            - standings
          properties: 
            standings:
              type: array
              items: 
                allOf: 
                  - $ref: '#/components/schemas/StandingsModel'
                  - type: object
                    required: 
                      - constructors_standings
                      - drivers_standings
                    properties: 
                      constructors_standings:
                        type: array
                        items:
                          $ref: '#/components/schemas/ConstructorsStandingsModel'
                      drivers_standings:
                        type: array
                        items:
                          $ref: '#/components/schemas/DriversStandingsModel'
    ConstructorsStandingsResponse:
      allOf: 
        - $ref: '#/components/schemas/DefaultResponse'
        - type: object
          required: 
            - standings
          properties: 
            standings:
              type: array
              items: 
                allOf: 
                  - $ref: '#/components/schemas/StandingsModel'
                  - type: object
                    required: 
                      - constructors_standings
                    properties: 
                      constructors_standings:
                        type: array
                        items:
                          $ref: '#/components/schemas/ConstructorsStandingsModel'
    DriversStandingsResponse:
      allOf: 
        - $ref: '#/components/schemas/DefaultResponse'
        - type: object
          required: 
            - standings
          properties: 
            standings:
              type: array
              items: 
                allOf: 
                  - $ref: '#/components/schemas/StandingsModel'
                  - type: object
                    required: 
                      - drivers_standings
                    properties: 
                      drivers_standings:
                        type: array
                        items:
                          $ref: '#/components/schemas/DriversStandingsModel'
    StandingsModel:
      description: The standings entity.
      type: object
      properties: 
        season:
          type: integer
          format: int32
          examples:
            - 2008
            - 2023
        round:
          type: integer
          format: int32
          examples:
            - 1
            - 18
      required: 
        - season
        - round
    StandingsDefaultModel:
      description: The base template of a standings entity.
      type: object
      required: 
        - position
        - position_text
        - points
        - wins
      properties: 
        position:
          type: integer
          format: int32
          examples:
            - 1
            - 2
        position_text:
          type: string
          examples:
            - 1
            - 2
        points:
          type: integer
          format: int32
          examples:
            - 98
            - 367
        wins:
          type: integer
          format: int32
          examples:
            - 5
            - 0
    ConstructorsStandingsModel:
      allOf:
        - $ref: '#/components/schemas/StandingsDefaultModel'
        - description: A constructor standings entry.
          type: object
          required:
            - constructor
          properties:
            constructor:
              $ref: '#/components/schemas/ConstructorModel'
    DriversStandingsModel:
      allOf:
        - $ref: '#/components/schemas/StandingsDefaultModel'
        - description: A driver standings entry.
          type: object
          required:
            - driver
            - constructors
          properties:
            driver:
              $ref: '#/components/schemas/DriverModel'
            constructors:
              type: array
              items:
                $ref: '#/components/schemas/ConstructorModel'
    Series:
      description: The championship series.
      type: string
      enum:
        - f1
    Status:
      type: object
      properties: 
        status:
          type: string
          examples:
            - "up and running"
            - "unavailable"
    DefaultResponse:
      type: object
      required:
        - series
        - limit
        - page
        - max_page
        - total
      properties:
        series:
          $ref: '#/components/schemas/Series'
        limit:
          description: The limit passed to the query.
          type: integer
          format: int32
          examples:
            - 30
            - 10
        page:
          description: The page queried.
          type: integer
          format: int32
          examples:
            - 1
            - 2
            - -1
        max_page:
          description: The maximum number of page to query.
          type: integer
          format: int32
          examples:
            - 10
            - 13
        total:
          description: The number of elements present in the response.
          type: integer
          format: int32
          examples:
            - 30
            - 10
            - 12
    ConstructorsResponse:
      allOf: 
        - $ref: '#/components/schemas/DefaultResponse'
        - type: object
          required:
            - constructors
          properties: 
            constructors:
              type: array
              items: 
                $ref: '#/components/schemas/ConstructorModel'
    DriversResponse:
      allOf: 
        - $ref: '#/components/schemas/DefaultResponse'
        - type: object
          required:
            - drivers
          properties: 
            drivers:
              type: array
              items: 
                $ref: '#/components/schemas/DriverModel'
    SeasonsResponse:
      allOf: 
        - $ref: '#/components/schemas/DefaultResponse'
        - type: object
          required:
            - drivers
          properties: 
            seasons:
              type: array
              items: 
                $ref: '#/components/schemas/SeasonModel'
    SeasonModel:
      type: object
      require:
        - season
        - url
      properties:
        season:
          type: integer
          format: int32
          examples:
            - 1950
            - 2024
        url:
          type: string
          examples:
            - "http://en.wikipedia.org/wiki/F1_2003"
    ConstructorModel:
      type: object
      required:
        - constructor_ref
        - name
        - url
      properties:
        constructor_ref:
          type: string
          examples:
            - ferrari
        name:
          type: string
          examples:
            - Scuderia Ferrari
        nationality:
          type: string
          examples:
            - Italian
        url:
          type: string
          examples:
            - "https://fr.wikipedia.org/wiki/Scuderia_Ferrari"
    DriverModel:
      type: object
      required:
        - driver_ref
        - url
        - given_name
        - family_name
      properties:
        driver_ref:
          type: string
          examples:
            - alonso
        permanent_number:
          type: integer
          format: int32
          examples:
            - 14
        code:
          type: string
          examples:
            - ALO
        url:
          type: string
          examples:
            - "http://en.wikipedia.org/wiki/Fernando_Alonso"
        given_name:
          type: string
          examples:
            - Fernando
        family_name:
          type: string
          examples:
            - Alonso
        date_of_birth:
          type: string
          examples:
            - "1981-07-29"
        nationality:
          type: string
          examples:
            - Spanish