# This open api service interface is implemented by API rest controllers.
openapi: "3.0.1"
info:
  title: "Passenger transport web services API"
  version: "1.0.0"
  description: |
    Passenger transport web services API to be consumed by external users. Department of Transport reserves the right to add properties to the model without incrementing API version numbers. 
    API consumers should ignore any unknown properties to avoid breaking changes as the API matures. 
    However, existing elements will not change data types or be removed without incrementing the version number. 
    Please note all operations are rate limited. 

paths:

  /v1/hello:
    get:
      summary: Health check method for testing login credentials
      tags:
        - endpoint
      responses:
        '200':
          description: OK
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          content:
            text/plain:
              schema:
                $ref: "#/components/schemas/String"
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorised
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /v1/ondemand-industry-api/drivers/{driver_licence_number}/ptd-status:
    get:
      description: Returns passenger transport driver(PTD) status for the given API access subscribed driver.
      parameters:
      - name: driver_licence_number
        in : path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 7
      - name: driver_surname
        in : query
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 40
      - name: date_of_birth
        in : query
        required: true
        schema:
          type: string
          format: date

      responses:
        "200":
          description: 200 response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: "string"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetPTDDetailsForDriverResponse"
        "400":
          description: 400 response - bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestResponse"
        "401":
          description: 401 response - Unauthorised, including when the authenticated
            user is not authorised to query online applications for the specified user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorisedErrorResponse"

  /v1/ondemand-industry-api/drivers/{driver_licence_number}:
    post:
      description: Add the driver to the driver dashboard
      parameters:
      - name: driver_licence_number
        in : path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 7
      - name: driver_surname
        in : query
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 40
      - name: date_of_birth
        in : query
        required: true
        schema:
          type: string
      responses:
        "200":
          description: 200 response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AddDriverSubscriptionResponse"
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: "string"
        "400":
          description: 400 response - bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestResponse"
        "401":
          description: 401 response - Unauthorised, including when the authenticated
            user is not authorised to query online applications for the specified user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorisedErrorResponse"

  /v1/ondemand-industry-api/drivers/{driver_licence_number}/remove:
    post:
      description: Remove the driver from the driver dashboard
      parameters:
      - name: driver_licence_number
        in : path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 7
      - name: driver_surname
        in : query
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 40
      - name: date_of_birth
        in : query
        required: true
        schema:
          type: string
          format: date
      responses:
        "200":
          description: 200 response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RemoveDriverSubscriptionResponse"
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: "string"
        "400":
          description: 400 response - bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestResponse"
        "401":
          description: 401 response - Unauthorised, including when the authenticated
            user is not authorised to query online applications for the specified user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorisedErrorResponse"

  /v1/ondemand-industry-api/drivers/subscription-export:
    get:
      description: Export a list of driver subscriptions for given parameters
      parameters:
      - name: filter_status
        in : query
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 20
      - name: export_type
        in : query
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 20

      responses:
        "200":
          description: 200 response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: "string"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetDriverSubscriptionExportContentResponse"
        "400":
          description: 400 response - bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestResponse"
        "401":
          description: 401 response - Unauthorised, including when the authenticated
            user is not authorised to query online applications for the specified user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorisedErrorResponse"

  /v1/ondemand-industry-api/vehicles/ptv-status:
    get:
      description: Returns the current passenger transport vehicle (PTV) status for a given vehicle
      parameters:
      - name: plate_number
        in : query
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 12
      - name: vin_number
        in : query
        required: false
        schema:
          type: string
          minLength: 1
          maxLength: 25
      responses:
        "200":
          description: 200 response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: "string"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetPTVDetailsForVehicleResponse"
        "400":
          description: 400 response - bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestResponse"
        "401":
          description: 401 response - Unauthorised, including when the authenticated
            user is not authorised to query online applications for the specified user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorisedErrorResponse"

  /v1/ondemand-industry-api/vehicles/{plate_number}:
    post:
      description: Add the vehicle to the vehicle dashboard
      parameters:
      - name: plate_number
        in : path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 12
      - name: vin_number
        in : query
        required: false
        schema:
          type: string
          minLength: 1
          maxLength: 25
      responses:
        "200":
          description: 200 response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AddVehicleSubscriptionResponse"
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: "string"
        "400":
          description: 400 response - bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestResponse"
        "401":
          description: 401 response - Unauthorised, including when the authenticated
            user is not authorised to query online applications for the specified user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorisedErrorResponse"

  /v1/ondemand-industry-api/vehicles/{plate_number}/remove:
    post:
      description: Remove the vehicle from the vehicle dashboard
      parameters:
      - name: plate_number
        in : path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 12
      - name: vin_number
        in : query
        required: false
        schema:
          type: string
          minLength: 1
          maxLength: 25
      responses:
        "200":
          description: 200 response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RemoveVehicleSubscriptionResponse"
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: "string"
        "400":
          description: 400 response - bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestResponse"
        "401":
          description: 401 response - Unauthorised, including when the authenticated
            user is not authorised to query online applications for the specified user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorisedErrorResponse"

  /v1/ondemand-industry-api/vehicles/export:
    get:
      description: Export a list of vehicle subscriptions for given parameters
      parameters:
      - name: filter_status
        in : query
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 20
      - name: export_type
        in : query
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 20

      responses:
        "200":
          description: 200 response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: "string"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetVehicleSubscriptionExportContentResponse"
        "400":
          description: 400 response - bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestResponse"
        "401":
          description: 401 response - Unauthorised, including when the authenticated
            user is not authorised to query online applications for the specified user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorisedErrorResponse"
        
components:
  parameters:
    correlationIdHeader:
      name: X-Correlation-ID
      in: header
      description: The unique identifier of the request
      required: false
      schema:
        type: string
        format: uuid

  schemas:
    Empty:
      type: "object"

    String:
      type: "string"

    # For HelloWorld test method
    ErrorDetail:
      title: ErrorDetail
      type: object
      x-examples:
        example-1:
          id: String
          detail: No actor could be found with the provided details
          code: NOT_FOUND_ACTOR
          source:
            pointer: /application/address
            parameter: customerNumber
      description: The details of an error. Conforming to national API standards.
      properties:
        id:
          type: string
          description: |
            Identifier of the specific error
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
        code:
          type: string
          description: An application-specific error code
        source:
          $ref: '#/components/schemas/ErrorSource'
      required:
        - detail
        - code
    ErrorSource:
      title: ErrorSource
      type: object
      x-examples:
        example-1:
          pointer: /application/address
          parameter: customerNumber
      description: Details of the source of the error
      properties:
        pointer:
          type: string
          description: 'JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].'
        parameter:
          type: string
          description: A string indicating which URI query parameter caused the error.
    Error:
      type: array
      title: Error
      description: A collection of errors
      minItems: 1
      items:
        $ref: '#/components/schemas/ErrorDetail'

    UnauthorisedErrorResponse:
      title: UnauthorisedErrorResponse
      type: object
      description: Access token is missing or invalid.
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/ErrorDetailsData"
          description: Access token is missing or invalid.

    BadRequestResponse:
      title: BadRequestResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/ErrorDetailsData"
          description: A list of messages indicating why the request was bad.

    ErrorDetailsData:
      title: ErrorDetailsData
      type: object
      description: The details of the error.
      properties:
        fieldName:
          type: string
          description: The identifier name of the field containing the error. Can be 'N/A'.
        message:
          type: string
          description: The error message.

    GetPTDDetailsForDriverResponse:
      title: GetPTDDetailsForDriverResponse
      type: object
      description: Response class which encapsulates the properties which are result of getting PTD details for a driver
      properties:
        driverStatus:
          type: string
          description: indicates whether the driver was found or not
        hrStatus:
          type: string
          description: H and R status of the driver subscribed
        ptdNumber:
          type: integer
          format: int64
          description: The PTD Authorisation number if found else null

    AddDriverSubscriptionResponse:
      title: AddDriverSubscriptionResponse
      type: object
      properties:
        resultStatus:
          type: string
          nullable: false
          minLength: 1
          maxLength: 100
          description: The result of the add driver subscription.
      required:
        - resultStatus

    AddVehicleSubscriptionResponse:
      title: AddVehicleSubscriptionResponse
      type: object
      properties:
        resultStatus:
          type: string
          nullable: false
          minLength: 1
          maxLength: 100
          description: The result of the add vehicle subscription.
      required:
        - resultStatus
        
    RemoveVehicleSubscriptionResponse:
      title: RemoveVehicleSubscriptionResponse
      type: object
      properties:
        resultStatus:
          type: string
          nullable: false
          minLength: 1
          maxLength: 100
          description: The result of the remove vehicle subscription.
      required:
        - resultStatus        
        
    RemoveDriverSubscriptionResponse:
      title: RemoveDriverSubscriptionResponse
      type: object
      properties:
        resultStatus:
          type: string
          nullable: false
          minLength: 1
          maxLength: 100
          description: The result of the remove driver subscription.
      required:
        - resultStatus

    GetDriverSubscriptionExportContentResponse:
      title: GetDriverSubscriptionExportContentResponse
      type: object
      description: The details of the exported driver subscriptions
      properties:
        mimeFileType:
          type: string
        fileType:
          type: string
          nullable: false
          enum:
            - CSV
        content:
          type: string
          format: byte
          nullable: false

    GetVehicleSubscriptionExportContentResponse:
      title: GetVehicleSubscriptionExportContentResponse
      type: object
      description: The details of the exported vehicles subscriptions
      properties:
        mimeFileType:
          type: string
        fileType:
          type: string
          nullable: false
          enum:
            - CSV
        content:
          type: string
          format: byte
          nullable: false
          
    GetPTVDetailsForVehicleResponse:
      title: GetPTVDetailsForVehicleResponse
      type: object
      description: Response class which encapsulates the properties which are result of getting PTV details for a vehicle
      properties:
        vehicleStatus:
          type: string
          description: Indicates whether the vehicle was found or not
        ptvStatus:
          type: string
          description: The PTV status of the vehicles
        ptvDefectStatus:
          type: string
          description: The PTV defect status of the vehicle