openapi: 3.0.0
x-zally-ignore: [224, 145]
info:
  x-audience: external-partner
  x-api-id: 'e61b68ba-e920-46a5-ac53-0884edf4abe2'
  title: Driver Administration API
  description: |
    This API provides access to drivers and driver identifications.

    ## Taxonomy

    * A `driver` is the account specific representation of a real person. It is unique within RIO.
    * A `driver` can have an optional set of identifications.
    * A `driver` can have an optional set of tags (aka. Fleet groups).

    * An `identification` is the data identifying a driver.
    * Identification can be of different types. Eg. EU Tachograph Card, RIO Driver Identification, Country specific driver license.

    ## Typical use cases

    * Retrieve all (active/archived) drivers for a certain account

    * Delete archived drivers

    * Create Driver Identification so he can login with his physical card
  version: '1.0.2'
  contact:
    name: Team Network
    email: rio_team_network@rio.cloud
    url: https://rio.cloud
tags:
  - name: Drivers
    description: Drivers
  - name: Identifications
    description: Identifications
  - name: Driver Tags
    description: Driver tag administration
paths:
  '/drivers':
    get:
      tags:
        - Drivers
      summary: Retrieve a list of Drivers
      description: |
        Rerieve all drivers matching the query parameters.

        ### Example use case

        * Retrieve all drivers:
          `GET /drivers`

        * Retrieve all archived drivers:
          `GET /drivers?status=archived`

        * Retrieve all active drivers:
          `GET /drivers?status=active`

        * Retrieve all drivers including their tags:
          `GET /drivers?embed=(tags)`

        * Retrieve all active drivers including their tags:
          `GET /drivers?status=active&embed=(tags)`

        * Retrieve all active drivers including their tags and identification:
          `GET /drivers?status=active&embed=(tags,identifications)`

        * Retrieve all active drivers including their tags and only eu-tachograph-card:
          `GET /drivers?status=active&embed=(tags,identifications)&identification_type=eu-tachograph-card`

      operationId: getDrivers
      parameters:
        - $ref: '#/components/parameters/account_id'
        - $ref: '#/components/parameters/identification'
        - $ref: '#/components/parameters/identification_type'
        - $ref: '#/components/parameters/status'
        - $ref: '#/components/parameters/embed'
        - $ref: '#/components/parameters/query'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/after'
        - $ref: '#/components/parameters/subject'
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/DriversEmbeddedList'
        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'
      security:
        - oauth2:
            - drivers.read
  '/drivers/{driver-id}':
    parameters:
      - $ref: '#/components/parameters/driver-id'
    get:
      tags:
        - Drivers
      summary: Retrieve a Driver
      operationId: getDriver
      parameters:
        - $ref: '#/components/parameters/embed'
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/DriverEmbedded'
        '404':
          description: Not Found
        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'
      security:
        - oauth2:
            - drivers.read
    put:
      tags:
        - Drivers
      summary: Create or update Driver
      operationId: putDriver
      requestBody:
        required: true
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/DriverRequest'
      responses:
        '201':
          description: Created
        '204':
          description: Updated
        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'
      security:
        - oauth2:
            - drivers.write
    delete:
      tags:
        - Drivers
      summary: Delete a Driver
      operationId: deleteDriver
      responses:
        '204':
          description: No content
        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'
      security:
        - oauth2:
            - drivers.write
  '/drivers/{driver-id}/identifications':
    parameters:
      - $ref: '#/components/parameters/driver-id'
      - $ref: '#/components/parameters/identification_type'
    get:
      tags:
        - Identifications
      summary: Get Identifications of a Driver
      operationId: getDriverIdentifications
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/IdentificationList'
        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'
      security:
        - oauth2:
            - drivers.read
  '/drivers/{driver-id}/identifications/{identification-id}':
    parameters:
      - $ref: '#/components/parameters/driver-id'
      - $ref: '#/components/parameters/identification-id'
    get:
      tags:
        - Identifications
      summary: Get an Identification of a Driver
      operationId: getDriverIdentification
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Identification'
        '404':
          description: Not Found
        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'

      security:
        - oauth2:
            - drivers.read
    put:
      tags:
        - Identifications
      summary: Create an Identification for a Driver
      operationId: putDriverIdentification
      requestBody:
        required: true
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/Identification'
      responses:
        '201':
          description: Created
        '204':
          description: Updated
        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'
      security:
        - oauth2:
            - drivers.write
    delete:
      tags:
        - Identifications
      summary: Delete an Identification of a Driver
      operationId: deleteDriverIdentification
      responses:
        '204':
          description: No content
        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'
      security:
        - oauth2:
            - drivers.write
  '/drivers/{driver-id}/tags':
    parameters:
      - $ref: '#/components/parameters/driver-id'
    get:
      tags:
        - Driver Tags
      summary: Get Tags of a Driver
      operationId: getDriverTags
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/TagList'
        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'
      security:
        - oauth2:
            - drivers.read
  '/drivers/{driver-id}/tags/{tag-id}':
    parameters:
      - $ref: '#/components/parameters/driver-id'
      - $ref: '#/components/parameters/tag-id'
    get:
      tags:
        - Driver Tags
      summary: Get a Tag of a Driver
      operationId: getDriverTag
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Tag'
        '404':
          description: Not Found
        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'
      security:
        - oauth2:
            - drivers.read
    put:
      tags:
        - Driver Tags
      summary: Tag a driver
      description: |
        Add the tag with the id specified in the path to the driver with the id specified in the path.
        The id in the path must match the id provided in the content body.
      operationId: putDriverTag
      requestBody:
        required: true
        content:
          'application/json':
            schema:
              $ref: '#/components/schemas/Tag'
      responses:
        '201':
          description: Created
        '204':
          description: Updated
        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'
      security:
        - oauth2:
            - drivers.write
    delete:
      tags:
        - Driver Tags
      summary: Untag a driver
      operationId: deleteTag
      responses:
        '204':
          description: No content
        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'
      security:
        - oauth2:
            - drivers.write
servers:
  - url: 'https://api.drivers.rio.cloud'
components:
  schemas:
    Id:
      type: string
      example: '67f5a0c2-6f14-4bb5-9278-b0af7dd45044'
      description: UUIDv4
      format: uuid
    DriverStatus:
      type: string
      x-extensible-enum:
        - active
        - archived
      example: active
    Email:
      type: string
      example: 'john.doe@example.com'
      description: E-mail
      format: email
      maxLength: 255
    IdentificationType:
      type: string
      x-extensible-enum:
        - eu-tachograph-card
        - rio-driver-identification
        - country-specific-driver-license
      example: eu-tachograph-card
    Identification:
      type: object
      required: [id, identification_type, identification]
      properties:
        id:
          $ref: '#/components/schemas/Id'
        identification_type:
          $ref: '#/components/schemas/IdentificationType'
        identification:
          type: string
          description: Identification
          example: 'D  1234567234111101'
    IdentificationList:
      type: object
      required: [ items ]
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Identification'
    Tag:
      type: object
      required: [ id ]
      properties:
        id:
          $ref: '#/components/schemas/Id'
    TagList:
      type: object
      required: [ items ]
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
    DriversEmbeddedList:
      type: object
      required: [ _links, items ]
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/DriverEmbedded'
        _links:
          $ref: '#/components/schemas/PaginationLinks'
    DriverEmbedded:
      allOf:
        - $ref: '#/components/schemas/DriverResponse'
        - type: object
          properties:
            _embedded:
              type: object
              properties:
                identifications:
                  type: array
                  items:
                    $ref: '#/components/schemas/Identification'
                tags:
                  type: array
                  items:
                    $ref: '#/components/schemas/Tag'
    PaginationLinks:
      type: object
      required: [ self ]
      description: |
        All links are (absolute) URLs.
        * The `self` link shows the current page.
        * The `next` link is only present if the result got paginated and there are still unfetched pages left.
          Follow the `next` link to get the next pages until the `next` link is not present anymore.
      properties:
        self:
          $ref: '#/components/schemas/Link'
        next:
          $ref: '#/components/schemas/Link'
    Link:
      type: object
      required: [ href ]
      properties:
        href:
          type: string
          example: 'https://...'
    DriverResponse:
      type: object
      required: [id, account_id]
      properties:
        id:
          $ref: '#/components/schemas/Id'
        account_id:
          $ref: '#/components/schemas/Id'
        status:
          $ref: '#/components/schemas/DriverStatus'
        email:
          $ref: '#/components/schemas/Email'
        first_name:
          type: string
          description: First name
          example: Peter
          maxLength: 255
        last_name:
          type: string
          description: Last name
          example: Pan
          maxLength: 255
        display_name:
          type: string
          description: |
            Backend calculated name to be used in UI.
            If no first name or last name is provided it will use the identification.
            If no identification is present it will fall back to use the string 'Unnamed driver'.
          example: Peter Pan
        phone_number:
          type: string
          description: A phone number must start with + followed by the country specific code and should not include whitespaces or special characters
          example: '+49123456789'
          maxLength: 255
        subject:
          type: string
          description: Subject as present in the JWT "sub" claim
          example: 'prod-rio-users:d6084519-e219-482e-b788-1050b40a5749'
    DriverRequest:
      type: object
      required: [ id, account_id, last_name ]
      properties:
        id:
          $ref: '#/components/schemas/Id'
        account_id:
          $ref: '#/components/schemas/Id'
        status:
          $ref: '#/components/schemas/DriverStatus'
        email:
          $ref: '#/components/schemas/Email'
        first_name:
          type: string
          description: First name
          example: Peter
          maxLength: 255
        last_name:
          type: string
          description: Last name. Cannot be blank.
          example: Pan
          minLength: 1
          maxLength: 255
        phone_number:
          type: string
          description: A phone number must start with + followed by the country specific code and should not include whitespaces or special characters
          example: '+49123456789'
          maxLength: 255
        subject:
          type: string
          description: Subject as present in the JWT "sub" claim
          example: 'prod-rio-users:d6084519-e219-482e-b788-1050b40a5749'
  parameters:
    driver-id:
      name: driver-id
      in: path
      required: true
      description: Driver Id
      schema:
        $ref: '#/components/schemas/Id'
    identification-id:
      name: identification-id
      in: path
      required: true
      description: Driver Identification Id
      schema:
        $ref: '#/components/schemas/Id'
    account_id:
      name: account_id
      in: query
      description: Account Id
      schema:
        $ref: '#/components/schemas/Id'
    tag-id:
      name: tag-id
      in: path
      required: true
      description: Tag Id
      schema:
        $ref: '#/components/schemas/Id'
    identification:
      name: identification
      in: query
      description: Identification identifier - In combination with identifcation_type
      schema:
        type: string
        example: 'D  1234567890'
    status:
      name: status
      in: query
      description: Driver status
      schema:
        $ref: '#/components/schemas/DriverStatus'
    query:
      in: query
      name: q
      description: >
        A query for searching. Currently no query language is defined, but we might add this later.
        This parameter is meant for UIs to pass simple search queries from human users.
        The interpretation of this string can change over time and we do not guarantee backwards compatibility.
      schema:
        type: string
    limit:
      in: query
      name: limit
      description: Limit the number of returned resources in list
      example: 30
      schema:
        type: integer
    after:
      in: query
      name: after
      description: offset for pagination
      example: 1530cf8-858d-11eb-aac5-784f43566792
      schema:
        type: string
    embed:
      name: embed
      in: query
      description: Embed optional sub resources
      schema:
        type: string
      examples:
        'identifications':
          value: '(identifications)'
        'tags':
          value: '(tags)'
    identification_type:
      name: identification_type
      in: query
      description: Driver Identification Type
      schema:
        $ref: '#/components/schemas/IdentificationType'
    subject:
      name: subject
      in: query
      description: The subject that is assigned to the driver
      schema:
        type: string
        example: 'prod-rio-users:14f5ccdb-4198-4dea-8792-76ecdd7b1a5e'
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: 'https://auth.iam.rio.cloud/oauth/token'
          scopes:
            drivers.read: Read access to drivers
            drivers.write: Write access to drivers
