openapi.yaml

openapi: 3.0.2


info:
  title: Fleet v2 HTTP API
  version: 2.6.0
  description: HTTP-based API for Fleet Protocol v2 serving for communication between the External Server and the end users.
  contact:
    email: jiri.strouhal@bringauto.com
  license:
    name: GPLv3
    url: https://www.gnu.org/licenses/gpl-3.0.en.html


servers:
  - url: /v2/protocol

tags:
- name: car
- name: device
- name: module

security:
  - AdminAuth: []
  - oAuth2AuthCode: []

paths:
  /login:
    get:
      x-openapi-router-controller: fleetv2_http_api.impl.controllers
      operationId: login
      security: []
      description:
        "Login using keycloak. If empty device is specified, will generate a url and device code used to authenticate a device. Tries to get token if device code is specified."
      tags:
        - login
      responses:
        '200':
          description: Returns either a standard keycloak token or a json used to authenticate a device.
        '302':
          description: Redirect to keycloak authentication.
        '500':
          description: Login failed due to internal server error.
      parameters:
        - $ref: '#/components/parameters/Device'

  /token_get:
    get:
      x-openapi-router-controller: fleetv2_http_api.impl.controllers
      operationId: token_get
      security: []
      description:
        "Callback endpoint for keycloak to receive jwt token."
      tags:
        - login
      responses:
        '200':
          description: Returns a standard keycloak token.
        '500':
          description: Login failed due to internal server error.
      parameters:
        - $ref: '#/components/parameters/kcState'
        - $ref: '#/components/parameters/kcSessionState'
        - $ref: '#/components/parameters/kcIss'
        - $ref: '#/components/parameters/kcCode'

  /token_refresh:
    get:
      x-openapi-router-controller: fleetv2_http_api.impl.controllers
      operationId: token_refresh
      security: []
      description:
        "Endpoint to receive jwt token from refresh token."
      tags:
        - login
      responses:
        '200':
          description: Returns a new standard keycloak token.
        '500':
          description: Token refresh failed due to internal server error.
      parameters:
        - $ref: '#/components/parameters/RefreshToken'

  /cars:
    get:
      x-openapi-router-controller: fleetv2_http_api.impl.controllers
      operationId: available_cars
      description:
        "Return list of available cars for all companies registered in the database."
      tags:
        - car

      responses:
        '200':
          description: A list of available cars.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Car'

              example:
                - company_name: 'company_x'
                  car_name: 'basic_car'
                - company_name: 'company_x'
                  car_name: 'better_car'
                - company_name: 'competing_company'
                  car_name: 'even_better_car'
        '500':
          description: Cannot display available cars due to internal server error.

      parameters:
        - $ref: '#/components/parameters/Wait'
        - $ref: '#/components/parameters/Since'

  /available-devices/{company_name}/{car_name}:
    get:
      x-openapi-router-controller: fleetv2_http_api.impl.controllers
      operationId: available-devices
      description:
        Return device Ids for all devices available for contained in the specified car.<br>
        For a single car module, the device Ids are returned as an object containing module Id and the list of device Ids. <br>

        If a module Id is specified, only a single such object is returned. <br>
        Otherwise, a list of such objects is returned, one for each module contained in the car. <br>
      tags:
        - module
      responses:
        '200':
          description: A list of available devices.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvailableDevices'

        '404':
          description: Cannot display available devices. Either company, car or module specified in the request does not exist.
        '500':
          description: Cannot display available devices due to internal server error.

      parameters:
      - $ref: '#/components/parameters/CompanyName'
      - $ref: '#/components/parameters/CarName'
      - $ref: "#/components/parameters/ModuleId"


  /status/{company_name}/{car_name}:
    parameters:
      - $ref: '#/components/parameters/CompanyName'
      - $ref: '#/components/parameters/CarName'

    get:
      x-openapi-router-controller: fleetv2_http_api.impl.controllers
      operationId: list_statuses
      description: It returns list of the Device Statuses.
      tags:
      - device
      responses:
        '200':
          description: A list of device statuses.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Message'
              example:
                [
                  {
                    "timestamp": 1700139157,
                    device_id: {module_id: 47, type: 2, role: "test_device", name: "Test Device"},
                    payload: {message_type: "STATUS", encoding: "BASE64", data: "V2FpdGluZw=="}
                  },
                  {
                    "timestamp": 1700145485,
                    device_id: {module_id: 47, type: 2, role: "test_device", name: "Test Device"},
                    payload: {message_type: "STATUS", encoding: "BASE64", data: "U3RpbGwgd29ya2luZw=="}
                  },
                  {
                    "timestamp": 1700145490,
                    device_id: {module_id: 47, type: 2, role: "test_device", name: "Test Device"},
                    payload: {message_type: "STATUS", encoding: "JSON", data: {"description": "Still working"}}
                  },
                ]
        '404':
          description: The statuses cannot be displayed. Either company, car or device specified in the request does not exist.
        '500':
          description: The statuses cannot be displayed due to internal server error.

      parameters:
        - $ref: '#/components/parameters/Since'
        - $ref: '#/components/parameters/Wait'


    post:
      x-openapi-router-controller: fleetv2_http_api.impl.controllers
      operationId: send_statuses
      description: Add statuses received from the Device.
      tags:
      - device
      responses:
        '200':
          description: The statuses have been sent.
        '404':
          description: The statuses could not been sent. Either company, car or device specified in the request does not exist.
        '500':
          description: The statuses could not been sent due to internal server error.
      requestBody:
        description: Statuses to be send by the device.
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Message'
            example:
              [
                {
                  device_id: {module_id: 47, type: 0, role: "test_device", name: "Test Device"},
                  payload: {message_type: "STATUS", encoding: "BASE64", data: "QnJpbmdBdXRv"}
                },
              ]


  /command/{company_name}/{car_name}:
    get:
      x-openapi-router-controller: fleetv2_http_api.impl.controllers
      operationId: list_commands
      description: Returns list of the Device Commands.
      tags:
      - device
      responses:
        '200':
          description: A list of commands.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Message'
              example:
                [
                  {
                    "timestamp": 1700139157,
                    device_id: {module_id: 47, type: 2, role: "test_device", name: "Test Device"},
                    payload: {message_type: "COMMAND", encoding: "BASE64", data: "U2F5IGhlbGxv"}
                  },
                ]
        '404':
          description: The commands cannot be displayed. Either company, car or device specified in the request does not exist.
        '500':
          description: The commands cannot be displayed due to internal server error.

      parameters:
        - $ref: '#/components/parameters/Since'
        - $ref: '#/components/parameters/Wait'

    parameters:
      - $ref: '#/components/parameters/CompanyName'
      - $ref: '#/components/parameters/CarName'

    post:
      x-openapi-router-controller: fleetv2_http_api.impl.controllers
      operationId: send_commands
      description: It adds new device Commands.
      tags:
      - device
      requestBody:
        description: Commands to be executed by the device.
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Message'
            example:
              [
                {
                  device_id: {module_id: 47, type: 2, role: "test_device", name: "Test Device"},
                  payload: {message_type: "COMMAND", encoding: "BASE64", data: "U2F5IGhlbGxv"}
                },
              ]

      responses:
        '200':
          description: The commands have been sent.
        '404':
          description: The commands have not been sent. Either company, car or device specified in the request does not exist.'
        '500':
          description: The commands have not been sent due to internal server error.


components:
  securitySchemes:
    AdminAuth:
      description: Authentication token for a administrator.
      type: apiKey
      in: query
      name: api_key
    oAuth2AuthCode:
      type: oauth2
      description: oAuth2 authorization
      flows:
        authorizationCode:
          authorizationUrl: https://keycloak.bringauto.com/realms/bringauto/protocol/openid-connect/auth
          tokenUrl: https://keycloak.bringauto.com/realms/bringauto/protocol/openid-connect/token
          refreshUrl: https://keycloak.bringauto.com/realms/bringauto/protocol/openid-connect/token
          scopes: {}


  parameters:
    Since:
      name: since
      description: A Unix timestamp; if specified, the method returns all messages inclusivelly newer than the specified timestamp \
        (i.e., messages with timestamp greater than or equal to the 'since' timestamp)
      in: query
      schema:
        type: integer
        nullable: true
        default: 0
      example: 1699262836

    ModuleId:
      name: module_id
      description: An Id of module, an unsigned integer.
      in: query
      schema:
        type: integer
        minimum: 0
        nullable: true
      example: 47

    Wait:
      name: wait
      description: An empty parameter. If specified, the method waits for predefined period of time, until some data to be sent in response are available.
      in: query
      schema:
        type: boolean
        nullable: true
        default: false
      example: false

    CarName:
      name: car_name
      description: Name of the Car, following a pattern ^[0-9a-z_]+$.
      in: path
      required: true
      schema:
        type: string
        pattern: ^[a-z0-9_]+$
      example: "test_car"

    CompanyName:
      name: company_name
      description: Name of the company, following a pattern ^[0-9a-z_]+$.
      in: path
      required: true
      schema:
        type: string
        pattern: ^[0-9a-z_]+$
      example: "test_company"

    Device:
      name: device
      description: Device code used for assisted authentication.
      in: query
      required: false
      schema:
        type: string
      example: e-VZfSM_-_TyPElL3i94...

    kcState:
      name: state
      description: State returned by keycloak authentication.
      in: query
      required: false
      schema:
        type: string
      example: your_state_info

    kcSessionState:
      name: session_state
      description: Session state returned by keycloak authentication.
      in: query
      required: false
      schema:
        type: string
      example: 167e141d-2f55-4d...

    kcIss:
      name: iss
      description: Code issuer returned by keycloak authentication.
      in: query
      required: false
      schema:
        type: string
      example: http%3A%2F%2Flocalhost%3A8081%2Frealms%2Fmaster

    kcCode:
      name: code
      description: Code used for jwt token generation returned by keycloak authentication.
      in: query
      required: false
      schema:
        type: string
      example: 5dea27d2-4b2d-48...

    RefreshToken:
      name: refresh_token
      description: Refresh token used for jwt token generation.
      in: query
      required: true
      schema:
        type: string
      example: eyJhbGciOiJIUzI1NiIsI...


  schemas:
    Message:
      description: Physical device or program located on the car.
      type: object
      required:
        - device_id
        - payload
      properties:
        timestamp:
          description: Unix timestamp of the message in milliseconds.
          type: integer
          example: 1699262836
        device_id:
          $ref: '#/components/schemas/DeviceId'
        payload:
          $ref: '#/components/schemas/Payload'

    AvailableDevices:
      description: List of Modules containint at least one device (specified by device Id) OR Module containing at least one device (specified by device Id).
      oneOf:
      - type: array
        items:
          $ref: '#/components/schemas/Module'
      - $ref: '#/components/schemas/Module'

    Module:
      description: A module containing at least one device (specified by device Id).
      type: object
      required:
        - module_id
        - device_list
      properties:
        module_id:
          description: Id (unsigned integer) of the module.
          type: integer
          minimum: 0
          example: 47
        device_list:
          description: List of Ids of devices contained in the module.
          type: array
          items:
            $ref: '#/components/schemas/DeviceId'
          example:
            [
              {module_id: 47, type: 2, role: "test_device", name: "Test Device"},
              {module_id: 47, type: 2, role: "test_device", name: "Test Device"},
            ]

    Car:
      description: A car assigned to a particular company.
      type: object
      required:
        - company_name
        - car_name
      properties:
        company_name:
          description: Name of the company, following a pattern ^[0-9a-z_]+$
          type: string
          pattern: ^[0-9a-z_]+$
          example: "test_company"
        car_name:
          description: Name of the Car, following a pattern ^[0-9a-z_]+$
          type: string
          pattern: ^[0-9a-z_]+$
          example: "test_car"

    DeviceId:
      description: Id of the device described with an object.
      type: object
      required:
        - module_id
        - type
        - role
        - name
      properties:
        module_id:
          description: Id (unsigned integer) of the module containing the device.
          type: integer
          minimum: 0
        type:
          description: Unsigned integer.
          type: integer
          minimum: 0
        role:
          description: "String description of the device role. It follows pattern ^[a-z0-9_]+$."
          type: string
          format: utf-8
          pattern: ^[a-z0-9_]+$
        name:
          description: UTF-8 encoded string.
          type: string
          format: utf-8
      example:
        module_id: 47
        type: 2
        role: "test_device"
        name: "Test Device"

    Payload:
      type: object
      description: Payload of the message, containing message type (status or command), encoding and data.
      required:
        - message_type
        - encoding
        - data
      properties:
        message_type:
          description: 'Type of the payload'
          type: string
          pattern: ^(STATUS)|(COMMAND)|(STATUS_ERROR)$
        encoding:
          description: 'Encoding of the payload'
          type: string
          pattern: ^(JSON)|(BASE64)$
        data:
          description: 'Payload data in "JSON" or "BASE64" format, depending on the encoding.'
          oneOf:
          - type: object
          - type: array
            items: {}
          - type: string
            format: base
      example:
        message_type: "STATUS"
        encoding: "BASE64"
        data: "QnJpbmdBdXRv"


# Cleaning up the statuses/commands:
#
# - every command and status has a TIMESTAMP and a KEY denoting a device,
#   to/by which the command/status was sent
#
# - on a regular basis (e.g., every minute), a part of commands/statuses is deleted,
#   if their timestamp is less or equal to current timestamp minus some specified period (e.g., 1 hour)
#
# - the method for posting new commands automatically detects, if a device key assigned
#   to this new command also correspond to at least on status in the database.
#   If not, the command is rejected
#
# - it is possible, that some commands remain in the database, whose device key does not now belong
#   to any status
#
# - if after N minutes a new status is posted with the device key assigned, that was once assigned
#   to other status (now deleted) in the database, all the commands having the same device key assigned
#   have to be deleted from the database. If the timestamp of such a command is GREATER, a warning
#   should be raised/logged (it is an invalid timestamp value, because, as mentioned previously,
#   no command could have been added after deleting the last status with the given device key)