data-intake-gateway-api.yaml

openapi: 3.0.1
info:
  title: Data Intake Gateway
  version: v3.4.2
  description: >-
      Please see the
      <a href='https://docs.google.com/document/d/15uNuPqwFcPLe6vKs_JgY5nPTy2isQ3WYUu4oyQ3cEfQ'>Data Intake Gateway Guide</a>
      to learn more; there are important workflow and implementation details to consider for all endpoints.
paths:
  /authentication/authenticate:
    post:
      tags:
        - Authentication
      summary: "Authenticate to the API"
      description: "Authenticate against the API with credentials"
      operationId: "authenticate"
      requestBody:
        description: "The username and password to authenticate with"
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticateModel'
      responses:
        "200":
          description: "Authentication successful"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationSuccessResponse'
              examples:
                example:
                  $ref: '#/components/examples/AuthenticatedResponseExample'
        "400":
          description: "Request was missing all or part of the required parameters"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  $ref: '#/components/examples/GenericErrorResponseExample'
        "401":
          description: "Credentials provided could not be used to authenticate successfully"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  $ref: '#/components/examples/GenericErrorResponseExample'
        "429":
          description: "Too many requests; rate limit quota exceeded; see public documentation"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  $ref: '#/components/examples/GenericErrorResponseExample'
        "503":
          description: "Service is unavailable"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  $ref: '#/components/examples/GenericErrorResponseExample'
  /authentication/refresh-token:
    post:
      security:
        - bearerAuth: []
      tags:
        - Authentication
      summary: "Refresh tokens using refresh and bearer tokens"
      description: ""
      operationId: "refresh-token"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenRefreshModel'
      responses:
        "200":
          description: "Token refresh was successful"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationSuccessResponse'
              examples:
                example:
                  $ref: '#/components/examples/AuthenticatedResponseExample'
        "400":
          description: "Request was missing all or part of the required parameters"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  $ref: '#/components/examples/GenericErrorResponseExample'
        "401":
          description: "Tokens provided could not be used to refresh successfully"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  $ref: '#/components/examples/GenericErrorResponseExample'
        "403":
          description: "Token was already refreshed and/or cannot be found"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  $ref: '#/components/examples/GenericErrorResponseExample'
        "429":
          description: "Too many requests; rate limit quota exceeded; see public documentation"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  $ref: '#/components/examples/GenericErrorResponseExample'
        "503":
          description: "Service is unavailable"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  $ref: '#/components/examples/GenericErrorResponseExample'
  /authentication/revoke-token:
    post:
      security:
        - bearerAuth: []
      tags:
        - Authentication
      summary: "Revoke current tokens"
      description: ""
      operationId: "revoke-token"
      requestBody:
        description: "Revoke the current set of tokens so they are no longer valid"
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenRefreshModel'
      responses:
        "202":
          description: "Token revocation request was accepted"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevokeTokenSuccessResponse'
              example:
                Error: []
                Data: "Refresh token revoked and user bearer token enqueued as blocked."
        "400":
          description: "Request was missing all or part of the required parameters"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  $ref: '#/components/examples/GenericErrorResponseExample'
        "401":
          description: "Tokens provided could not be used to revoke successfully"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  $ref: '#/components/examples/GenericErrorResponseExample'
        "403":
          description: "Token has already been revoked and/or cannot be found"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  $ref: '#/components/examples/GenericErrorResponseExample'
        "429":
          description: "Too many requests; rate limit quota exceeded; see public documentation"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  $ref: '#/components/examples/GenericErrorResponseExample'
        "503":
          description: "Service is unavailable"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  $ref: '#/components/examples/GenericErrorResponseExample'
  /invalidrecords:
    get:
      security:
        - bearerAuth: []
      tags:
        - Invalid Records
      parameters:
        - name: nextResultKey
          in: query
          schema:
            type: integer
        - name: numberOfResults
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 50000
            default: 1000
      responses:
        "200":
          description: "Fetch batch of invalid records"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRecordsResponse'
              example:
                Error: []
                Data:
                  NextResultKey: 1002154023
                  CurrentResultKey: 1002152089
                  TotalNumberOfInvalidRecords: 16545
                  CurrentNumberOfInvalidRecords: 200
                  InvalidRecords:
                    - BaseRecord:
                        SerialNo: "2396122106100"
                        Type: "GenericStatusRecord"
                        DateTime: "2021-02-10T01:00:00.500Z"
                        Code: 7
                        Value: 0
                      Cause: "Reason message was rejected"
                      TimeStamp: "2021-02-10T02:00:00Z"
                      UserId: "dig@geo.tab"
                    - BaseRecord:
                        SerialNo: "6605174986852"
                        Type: "StatusRecord"
                        DateTime: "2021-02-10T01:00:00.010Z"
                        Code: 12
                        Value: 5
                      Cause: "Reason message was rejected"
                      TimeStamp: "2021-02-10T02:01:00Z"
                      UserId: "dig@geo.tab"
        "400":
          description: "Request was missing all or part of the required parameters"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  $ref: '#/components/examples/GenericErrorResponseExample'
        "401":
          description: "Tokens provided could not be used to authenticate successfully"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  $ref: '#/components/examples/GenericErrorResponseExample'
        "503":
          description: "Service is unavailable"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  $ref: '#/components/examples/GenericErrorResponseExample'
  /records:
    post:
      security:
        - bearerAuth: []
      tags:
        - Records
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                anyOf:
                  - $ref: '#/components/schemas/AccelerationRecord'
                  - $ref: '#/components/schemas/BinaryRecord'
                  - $ref: '#/components/schemas/BluetoothRecord'
                  - $ref: '#/components/schemas/DriverChangeRecord'
                  - $ref: '#/components/schemas/GenericFaultRecord'
                  - $ref: '#/components/schemas/GenericStatusRecord'
                  - $ref: '#/components/schemas/GpsRecord'
                  - $ref: '#/components/schemas/J1708FaultRecord'
                  - $ref: '#/components/schemas/J1939FaultRecord'
                  - $ref: '#/components/schemas/ObdiiFaultRecord'
                  - $ref: '#/components/schemas/StatusRecord'
                  - $ref: '#/components/schemas/VinRecord'
              maxItems: 5000
              example:
                - SerialNo: "2396122106100"
                  Type: "VinRecord"
                  DateTime: "2021-02-10T01:00:00Z"
                  VehicleIdentificationNumber: "1NZI3SA5WPAJE2YR3"
                - SerialNo: "8378832278466"
                  Type: "StatusRecord"
                  DateTime: "2021-02-10T01:00:01.500Z"
                  Code: 12
                  Value: 5
      responses:
        "202":
          description: "Records accepted for processing"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordsResponse'
              example:
                Error: []
                Data: "feeac962-4496-4458-a489-e2d9b4ea12ec"
        "400":
          description: "Request was missing all or part of the required parameters"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  $ref: '#/components/examples/GenericErrorResponseExample'
        "413":
          description: "Request payload was too large (size in bytes or too many records)"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  $ref: '#/components/examples/GenericErrorResponseExample'
        "503":
          description: "Service is unavailable"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  $ref: '#/components/examples/GenericErrorResponseExample'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    AuthenticationStatus:
      type: object
      properties:
        Authenticated:
          type: boolean
        UserId:
          type: string
        BearerToken:
          $ref: "#/components/schemas/Token"
        RefreshToken:
          $ref: "#/components/schemas/Token"
    AuthenticationSuccessResponse:
      type: object
      properties:
        Error:
          $ref: "#/components/schemas/ResponseErrors"
        Data:
          $ref: '#/components/schemas/AuthenticationStatus'
    RevokeTokenSuccessResponse:
      type: object
      properties:
        Error:
          $ref: "#/components/schemas/ResponseErrors"
        Data:
          type: string
    InvalidRecordsResponse:
      type: object
      properties:
        Error:
          $ref: "#/components/schemas/ResponseErrors"
        Data:
          $ref: '#/components/schemas/InvalidRecordSet'
    RecordsResponse:
      type: object
      properties:
        Error:
          $ref: "#/components/schemas/ResponseErrors"
        Data:
          type: string
          format: uuid
    ResponseErrors:
      type: array
      items:
        type: string
    ErrorResponse:
      type: object
      properties:
        Error:
          $ref: "#/components/schemas/ResponseErrors"
        Data:
          type: string
    AuthenticateModel:
      required:
        - Password
        - Username
      type: object
      properties:
        Username:
          type: string
        Password:
          type: string
      additionalProperties: false
    TokenRefreshModel:
      required:
        - BearerToken
        - RefreshToken
      type: object
      properties:
        BearerToken:
          type: string
        RefreshToken:
          type: string
      additionalProperties: false
    Token:
      type: object
      properties:
        TokenString:
          type: string
        Expires:
          type: string
          format: date-time
        Created:
          type: string
          format: date-time
    AccelerationRecord:
      description: A data record class that contains acceleration data.
      allOf:
        - $ref: '#/components/schemas/BaseRecord'
        - type: object
          properties:
            X:
              type: integer
              format: int16
              description: The X-axis acceleration (forward or backward) in milli-g (1000 milli-g = 1 G Gravitational force).
            Y:
              type: integer
              format: int16
              description: The Y-axis acceleration (right or left) in milli-g (1000 milli-g = 1 G Gravitational force).
            Z:
              type: integer
              format: int16
              description: The Z-axis acceleration (up or down) in milli-g (1000 milli-g = 1 G Gravitational force).
    BaseRecord:
      type: object
      description: An abstract data record class (all fields are required).
      properties:
        Type:
          type: string
          description: Indicates the type of record.
        DateTime:
          type: string
          format: date-time
          description: Date and time of the record in the ISO 8601 RFC3339, UTC zulu format yyyy-MM-ddTHH:mm:ss.ffffffZ is recommended. See DIG guide *Working with Dates* section for more details.
        SerialNo:
          type: string
          description: Device serial number.
      additionalProperties: false
    BinaryRecord:
      description: A data record class that supports arbitrary binary data.
      allOf:
        - $ref: '#/components/schemas/BaseRecord'
        - type: object
          properties:
            Data:
              type: string
              format: byte
              maxLength: 32745
              description: Arbitrary binary payload, Base64 encoded. Maximum size of 32745 bytes.
    DriverChangeRecord:
      description: A data record class that contains driver change data.
      allOf:
        - $ref: '#/components/schemas/BaseRecord'
        - type: object
          properties:
            KeyType:
              type: integer
              minimum: 0
              maximum: 255
              description: The key type.
            DriverId:
              type: string
              format: byte
              maxLength: 239
              description: Driver ID, Base64 encoded.
    GenericFaultRecord:
      description: A data record class that contains generic fault data.
      allOf:
        - $ref: '#/components/schemas/BaseRecord'
        - type: object
          properties:
            Code:
              type: integer
              minimum: 128
              maximum: 1999
              description: Diagnostic ID code (of type fault). (Range >=128, <=1999)
            FaultStateActive:
              type: boolean
              description: A value indicating whether the fault state is active.
    GenericStatusRecord:
      description: A data record class that supports generalised data from a telematics device. Supports a specific set of codes.
      allOf:
        - $ref: '#/components/schemas/StatusRecord'
        - type: object
    GpsRecord:
      description: A data record class that contains latitudinal and longitudinal location data and speed (km/h). Other ancillary flags are also supported.
      allOf:
        - $ref: '#/components/schemas/BaseRecord'
        - type: object
          properties:
            IsAuxiliary1On:
              type: boolean
              description: A value indicating whether the auxiliary is on.
            IsAuxiliary2On:
              type: boolean
              description: A value indicating whether the auxiliary is on.
            IsAuxiliary3On:
              type: boolean
              description: A value indicating whether the auxiliary is on.
            IsAuxiliary4On:
              type: boolean
              description: A value indicating whether the auxiliary is on.
            IsAuxiliary5On:
              type: boolean
              description: A value indicating whether the auxiliary is on.
            IsAuxiliary6On:
              type: boolean
              description: A value indicating whether the auxiliary is on.
            IsAuxiliary7On:
              type: boolean
              description: A value indicating whether the auxiliary is on.
            IsAuxiliary8On:
              type: boolean
              description: A value indicating whether the auxiliary is on.
            IsGpsValid:
              type: boolean
              description: A value indicating whether the GPS is valid.
            IsIgnitionOn:
              type: boolean
              description: A value indicating whether the ignition is on.
            Latitude:
              type: number
              format: float (4-bytes signed)
              description: The latitude.
            Longitude:
              type: number
              format: float (4-bytes signed)
              description: The longitude.
            Speed:
              type: number
              format: float (4-bytes signed)
              description: The speed in kilometers per hour.
    J1708FaultRecord:
      description: A data record class that contains J1708 fault data.
      allOf:
        - $ref: '#/components/schemas/BaseRecord'
        - type: object
          properties:
            MessageId:
              type: integer
              format: uint8
              minimum: 0
              maximum: 255
              description: Identifier for the component sending the message.
            ParameterId:
              type: integer
              format: uint16
              minimum: 0
              maximum: 511
              nullable: true
              description: Parameter identification without a related Subsystem ID.
            SubsystemId:
              type: integer
              format: uint16
              minimum: 0
              maximum: 511
              nullable: true
              description: Identifies a section of the control system without a related Parameter ID.
            FailureModeIdentifier:
              type: integer
              format: uint8
              minimum: 0
              maximum: 15
              description: Failure mode identifier associated with a diagnostic trouble code.
            OccurrenceCount:
              type: integer
              format: uint8
              minimum: 0
              maximum: 255
              description: Number of faults.
            FaultStateActive:
              type: boolean
              description: A value indicating whether the fault state is active.
    J1939FaultRecord:
      description: A data record class that contains J1939 fault data.
      allOf:
        - $ref: '#/components/schemas/BaseRecord'
        - type: object
          properties:
            SuspectParameterNumber:
              type: integer
              description: Unique number assigned to every suspect parameter number (SPN).
            FailureModeIdentifier:
              type: integer
              format: uint8
              minimum: 0
              maximum: 255
              description: Failure mode identifier associated with a diagnostic trouble code.
            OccurrenceCount:
              type: integer
              format: uint8
              minimum: 0
              maximum: 255
              description: Number of times this fault has been recorded.
            SourceAddress:
              type: integer
              format: uint8
              minimum: 0
              maximum: 255
              description: The address of a controller application.
            MalfunctionLamp:
              type: boolean
              description: Lamp to indicate when there is an emission related trouble code active (MIL).
            RedStopLamp:
              type: boolean
              description: Lamp to indicate a problem that is severe enough to warrant stopping the vehicle (RSL).
            AmberWarningLamp:
              type: boolean
              description: Lamp to indicate a problem with the vehicle system but the vehicle does not need to be stopped immediately (AWL).
            ProtectWarningLamp:
              type: boolean
              description: Lamp to indicate a problem with a vehicle system that is most likely not electronic subsystem related (PL).
            FaultStateActive:
              type: boolean
              description: A value indicating whether the fault state is active.
    ObdiiFaultRecord:
      description: A data record class that contains OBD-II fault data.
      allOf:
        - $ref: '#/components/schemas/BaseRecord'
        - type: object
          properties:
            Code:
              type: string
              description: Trouble code.
            FaultStateActive:
              type: boolean
              description: A value indicating whether the fault state is active.
    StatusRecord:
      description: A data record class that contains status data.
      allOf:
        - $ref: '#/components/schemas/BaseRecord'
        - type: object
          properties:
            Code:
              type: integer
              description: The diagnostic code (of type status). (Range <=127, >=2000)
            Value:
              type: integer
              description: The value of the diagnostic. (valid values depend on diagnostic code)
    VinRecord:
      description: A data record class that contains vehicle identification data.
      allOf:
        - $ref: '#/components/schemas/BaseRecord'
        - type: object
          properties:
            VehicleIdentificationNumber:
              type: string
              description: Vehicle Identification Number.
    BluetoothRecord:
      description: A data record class that contains bluetooth data.
      allOf:
        - $ref: '#/components/schemas/BaseRecord'
        - type: object
          properties:
            Address:
              type: string
              description: The string MAC address of the Bluetooth sensor  (e.g. FF:FF:FF:00:AA:9B).
            Data:
               type: number
               format:  float (4-bytes signed)
               description: The floating point value of the data. The meaning and unit of measure is dependent on data type.
            DataType:
               type: integer
               minimum: 0
               maximum: 255
               description: Identifies the type of bluetooth data contained in the data field.
    InvalidRecordSet:
      type: object
      description: A data record class that contains invalid record data.
      properties:
        NextResultKey:
          type: integer
          format: int64
          description: Cursor pointing to the next record after the current set.
        CurrentResultKey:
          type: integer
          format: int64
          description: Cursor pointing to the start of the current results.
        TotalNumberOfInvalidRecords:
          type: integer
          format: int64
          description: Total number of invalid records for the current user.
        CurrentNumberOfInvalidRecords:
          type: integer
          format: int64
          description: Number of invalid records in the current set.
        InvalidRecords:
          type: array
          items:
            $ref: '#/components/schemas/InvalidRecord'
          description: Array of InvalidRecords.
      additionalProperties: false
    InvalidRecord:
      type: object
      description: A data record class that contains data which is not accepted by the API.
      properties:
        BaseRecord:
          $ref: '#/components/schemas/BaseRecord'
        Cause:
          type: string
          nullable: true
          description: Reason the record was rejected.
        TimeStamp:
          type: string
          format: date-time
          description: Date and time the record was marked invalid in the ISO 8601 RFC3339 format.
        UserId:
          type: string
          nullable: true
          description: ID of the user who owns this record.
      additionalProperties: false
  examples:
    GenericErrorResponseExample:
      summary: "Sample of a generic error response"
      description: "Note that Error and Data are mutually exclusive. In error condition Error is populated with one or more errors; Data will be empty."
      value:
        Error: [ "Error message here" ]
        Data: {}
    AuthenticatedResponseExample:
      summary: "Sample of a successful authenticated response."
      value:
        Error: [ ]
        Data:
          Authenticated: true
          UserId: "dig@geo.tab"
          BearerToken:
            TokenString: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6ImRpZ0BnZW8udGFiIiwibmJmIjoxNjEyODQ2ODEwLCJleHAiOjE2MTMxMDYwMTAsImlhdCI6MTYxMjg0NjgxMH0.pXS0ehnRCwZSzGNLSYGlh_oJCnXieFZBu7HBV6y0b5Q"
            Created: "2019-07-26T00:00:10"
            Expires: "2019-07-26T00:00:10"
          RefreshToken:
            TokenString: "m=+tunBX6uDBY/Rk9OUQeZdCdmaQgzPHdGvVH2B3cuCXwjADdqvD44vyCr0Z"
            Created: "2019-07-26T00:00:10"
            Expires: "2019-07-26T00:00:10"