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