openapi: 3.0.0
info:
  title: Tachograph File Archive
  version: 1.2.1
  description: Access meta data about about stored tachograph files, download and upload tachograph files
  contact:
    name: Team Compliant
    url: https://rio.cloud
    email: team_compliant@man.eu
  x-api-id: f4cffb37-949a-4ddd-be04-432a7e1dbecb
  x-audience: external-partner

x-zally-ignore:
  - 101
  - 172
  - 224

servers:
  - url: https://api.remotedownload.rio.cloud/partner

paths:
  /files:
    get:
      summary:
        Get (paged) file informations or zip of files based on content-header.
        Results are sorted by file-name ascending.
      description: |
        ## Accept Header
        When sending `Accept`-Header `application/json` API will respond with a description in JSON for the files matching query parameters.
        When sending `Accept`-Header `application/zip` API will respond with a compressed file in ZIP format containing all the tachograph files itself matching request paramters.

        ## Examples:
        ### Get all files

        `GET /files`

        ### Get all files that are not already exported by requesting client.

        `GET /files?already_exported=false`

        ### Get all files between two dates with paging information. `From` and `to` refering to FileMetadataModel::time_created.

        `GET /files?from=2018-07-01T08:42:05.346Z&to=2019-05-28T08:42:05.346Z&offset=10&limit=10`

        ### Get Files from driver between two dates. `From` and `to` refering to FileMetadataModel::time_created.

        `GET /files?file_type=driver&from=2018-07-01T08:42:05.346Z&to=2019-05-28T08:42:05.346Z`

        ### Get Files from vehicles between two dates that are not already exported by requesting client. `From` and `to` refering to FileMetadataModel::time_created.

        `GET /files?file_type=vehicle&from=2018-07-01T08:42:05.346Z&to=2018-05-28T08:42:05.346Z&already_exported=false`

        ### Get Files relating to specific driver with paging information

        `GET /files?offset=0&limit=10&driver_id=7b290aff-6eab-47a3-9b61-e9f6c9dfc906`

      parameters:
        - $ref: "#/components/parameters/fleet-id"
        - $ref: "#/components/parameters/driver-id"
        - $ref: "#/components/parameters/equipment-id"
        - $ref: "#/components/parameters/from"
        - $ref: "#/components/parameters/to"
        - $ref: "#/components/parameters/offset"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/file-type"
        - $ref: "#/components/parameters/already-exported"
      security:
        - oauth2:
            - tachograph-partner.read
      responses:
        200:
          description: |
            Queried filearchive with given parameters and returning in expected format.
            Requester can set the appropriate format by specifying in "Accept"-Header.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FileMetadataResponse"
            application/zip:
              schema:
                type: string
                format: binary
        default:
          description: >-
            error occurred - see status code and problem object for more
            information.
          content:
            application/problem+json:
              schema:
                $ref: "https://opensource.zalando.com/problem/schema.yaml#/Problem"
    post:
      summary: "Upload a file"
      description: |
        ## Example:

        ### Upload a file
        `POST /files?fleet_id=d304220d-430a-42fc-939a-b01c50ceef04&file_name=upload.ddd`

        Body must contain file in binary format
      parameters:
        - $ref: "#/components/parameters/fleet-id-required"
        - $ref: "#/components/parameters/file-name"
      requestBody:
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      security:
        - oauth2:
            - tachograph-partner.write
      responses:
        201:
          description: Created the file
        default:
          description: >-
            error occurred - see status code and problem object for more
            information.
          content:
            application/problem+json:
              schema:
                $ref: "https://opensource.zalando.com/problem/schema.yaml#/Problem"
  /files/{file-id}:
    get:
      summary: Get a file itself or file metadata via file-id based on content-type header
      description: |
        ## Example:

        ### Get file via file ID 148

        `GET /files/148`
      parameters:
        - $ref: "#/components/parameters/file-id"
      security:
        - oauth2:
            - tachograph-partner.read
      responses:
        200:
          description: |
            Queried filearchive with given ID and returning in expected format.
            Requester can set the appropriate format by specifying in "Accept"-Header.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FileMetadataResponse"
            application/octet-stream:
              schema:
                type: string
                format: binary
        default:
          description: >-
            error occurred - see status code and problem object for more
            information.
          content:
            application/problem+json:
              schema:
                $ref: "https://opensource.zalando.com/problem/schema.yaml#/Problem"

components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.iam.rio.cloud/oauth/token
          scopes:
            tachograph-partner.read: Access right to read files and metadata from archive
            tachograph-partner.write: Access right to upload files

  parameters:
    file-id:
      name: file-id
      in: path
      description: "File identification"
      required: true
      schema:
        type: integer
        format: int32
    equipment-id:
      name: equipment_id
      in: query
      description: "Equipment identification"
      required: false
      schema:
        type: string
    driver-id:
      name: driver_id
      in: query
      description: "Driver identification"
      required: false
      schema:
        type: string
    fleet-id:
      name: fleet_id
      in: query
      description: "Fleet identification"
      required: false
      schema:
        type: string
    fleet-id-required:
      name: fleet_id
      in: query
      description: "Fleet identification"
      required: true
      schema:
        type: string
    from:
      name: from
      required: false
      in: query
      description: "UTC value formatted as date-time (see: RFC 3339, section 5.6). Refering to FileMetadataModel::time_created."
      schema:
        type: string
        format: date-time
    to:
      name: to
      required: false
      in: query
      description: "UTC value formatted as date-time (see: RFC 3339, section 5.6). Refering to FileMetadataModel::time_created."
      schema:
        type: string
        format: date-time
    offset:
      name: offset
      required: false
      in: query
      description: "Pagination: number of elements to skip"
      schema:
        type: integer
        format: int32
        default: 0
    limit:
      name: limit
      in: query
      description: "Pagination: number of elements on the page"
      required: false
      schema:
        type: integer
        format: int32
        default: 10
        maximum: 100
    file-name:
      name: file_name
      in: query
      required: true
      description: Name of the file
      schema:
        type: string
    file-type:
      name: file_type
      in: query
      description: defines the type of file
      x-extensible-enum:
        - unknown
        - driver
        - vehicle
        - workshop
      schema:
        type: string
    already-exported:
      name: already_exported
      in: query
      description: Filter to show only files that are / or are not already exported by requesting IAM client. When not set, the response will contain all files.
      schema:
        type: boolean

  schemas:
    FileMetadataResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/FileMetadataModel"
        count:
          type: integer
          format: int32
          readOnly: true
        total_count:
          type: integer
          format: int32
          readOnly: true
        pagination:
          $ref: "#/components/schemas/PaginationModel"
    FileMetadataModel:
      type: object
      properties:
        reference_id:
          type: string
          format: uuid
          description: In case of file_type driver this is the driverId, when file_type vehicle this is the vehicle id / asset  id, for other cases this is empty
        file_id:
          type: integer
          format: int32
          description: File identification. Globally unique.
        customer_id:
          type: string
          description: Customer id
        file_name:
          type: string
          description: File name
        size:
          type: integer
          format: int32
          description: File size
        file_type:
          type: string
          description: File type
          x-extensible-enum:
            - unknown
            - driver
            - vehicle
            - workshop
        has_sections_valid:
          type: boolean
          description: Has sections valid
        is_corrupted:
          type: boolean
          description: Is corrupted
        time_created:
          type: string
          format: date-time
          description: "UTC value formatted as date-time (see: RFC 3339, section 5.6)"
        time_modified:
          type: string
          format: date-time
          description: "UTC value formatted as date-time (see: RFC 3339, section 5.6)"
        created_by:
          type: string
          description: "Created by"
        modified_by:
          type: string
          description: "Last modified by"
        exported:
          type: boolean
          description: "If the file was already exported by the requesting IAM client"
        exported_at:
          type: string
          format: date-time
          description: "date and time of last export by requesting IAM client (UTC value formatted as date-time). If there was no export by the requesting client before, this value is null."
      description: Tachograph File Metadata Response
    PaginationModel:
      type: object
      properties:
        offset:
          type: integer
          format: int32
          readOnly: true
        limit:
          type: integer
          format: int32
          readOnly: true
        previous:
          type: string
          readOnly: true
        next:
          type: string
          readOnly: true
