openapi: '3.0.1'
info:
  title: W3C Vehicle Information Specification REST API documentation
  version: 0.0.1
  description: Documentation for initial implementation of REST API for accessing VIS information
    based on Web-Sockets definition. <br><br>
    Implemented REST API re-use defined target paths for both requests and responses. <br><br>
    Current REST API definition do not support request with passing data in HTTP body of requests
    due to current simple use-cases.
    But transferring request data through request HTTP body could be investigated as a means of more
    complex GET/SET requests; e.g. retrieve/update multiple signals in single request by
    providing JSON array of signals, more complex query support of signal states/values, etc... <br><br>
    REST API supports both existing Web-socket signal path format with '.' as path separator, and more
    'REST-like' '/' path separator. <br><br>
    Due to REST API design supporting by default only client -> server flow, support for
    'subscribe' and 'unsubscribe' requests is intentionally ommitted.
    It should be technically possible to add subscribe functionality, but this is currently out-of-scope
    and could be discussion point in future.<br><br>
    This API definition proposes explicit API path and API version information through base URL.
    This allows us to cleanly support different versions of API and|or W3C VIS standard. Aditional REST API
    endpoint could be added to support providing information about versions' support of server
    (through e.g. /vss/api/versions endpoint), but this is currently out-of-scope and could be
    discussion point in future.

  contact:
    email: kuksa-dev@eclipse.org
    url: 'https://www.eclipse.org/kuksa/'
  license:
    name: Eclipse Public License v2.0
    url: 'https://www.eclipse.org/legal/epl-2.0/'
  termsOfService: 'https://www.eclipse.org/legal/termsofuse.php'
servers:
  - url: http://localhost:8090/vss/api/v1/
  - url: https://localhost:8090/vss/api/v1/
tags:
- name: signals
  description: "Acces specific signal or signal branch information"
- name: metadata
  description: "Access metadata information"
- name: authorize
  description: "Authorize user access"

components:
  parameters:

    signalBranchPathWithDots:
      name: signalBranchPathWithDots
      in: path
      description: String defining branch structure, where branch items are separated by '.' character.
      schema:
        type: string
        pattern: '^[A-Za-z0-9\.]+$'
      required: true
      example: Vehicle.Drivetrain.Transmission

    signalBranchPathWithSlashes:
      name: signalBranchPathWithSlashes
      in: path
      description: String defining branch structure, where branch items are separated by '/' character.
      schema:
        type: string
        pattern: '^[A-Za-z0-9/]+$'
      allowReserved: true
      required: true
      example: Vehicle/Drivetrain/Transmission

    signalId:
      name: signalId
      in: path
      description: Signal identifier
      schema:
        type: string
        pattern: '^[A-Za-z0-9]+$'
      required: true
      example: "TravelledDistance"

    token:
      name: token
      in: query
      description: JWT token string in 'base64url' format
      required: true
      schema:
        type: string
        format: base64url

    signalValue:
      name: value
      in: query
      description: Signal value
      required: true
      schema:
        type: integer
      example: 123

  responses:

    Success:
      description: "Request completed successfully"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SuccessResponse'

    SuccessAuthorize:
      description: "Authorize request completed successfully"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuthSuccessResponse'

    BadRequestRsp:
      description: "The specified resource was not found"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BadRequestContent'

    UnauthorizedRsp:
      description: "Provided JWT token could not be authorized"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedContent'

    ForbiddenRsp:
      description: "Access to resource is forbidden"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ForbiddenContent'

    NotFoundRsp:
      description: "Requested resource not found"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFoundContent'

  schemas:

    Action:
      type: string
      enum: ['get', 'set', 'getMetadata', 'authorize']
      description: Action request

    Timestamp:
      type: integer
      description: Timestamp of event
      example: 615154112

    RequestId:
      type: integer
      description: Unique request identifier
      example: 817151

    SuccessResponse:
      type: object
      properties:
        action:
          $ref: '#/components/schemas/Action'
        path:
          type: string
          description: Requested resource path
          example: "Vehicle.Drivetrain.Transmission.TravelledDistance"
        requestId:
          $ref: '#/components/schemas/RequestId'
        timestamp:
          $ref: '#/components/schemas/Timestamp'
        value:
          type: object
          description: Response content

    AuthSuccessResponse:
      type: object
      properties:
        TTL:
          type: integer
          description: Token expiration time
          example: 123456
        action:
          type: string
          example: authorize
        requestId:
          $ref: '#/components/schemas/RequestId'
        timestamp:
          $ref: '#/components/schemas/Timestamp'

    ErrorDesc:
      type: object
      properties:
        number:
          type: integer
          description: "HTML status code"
          example: 400, 401, 403, 404
        reason:
          type: string
          description: "Error reason"
        message:
          type: string
          description: "Error description"

    BadRequestContent:
      type: object
      properties:
        action:
          $ref: '#/components/schemas/Action'
        error:
          $ref: '#/components/schemas/ErrorDesc'
        timestamp:
          $ref: '#/components/schemas/Timestamp'

    UnauthorizedContent:
      type: object
      properties:
        action:
          $ref: '#/components/schemas/Action'
        error:
          $ref: '#/components/schemas/ErrorDesc'
        requestId:
          $ref: '#/components/schemas/RequestId'
        timestamp:
          $ref: '#/components/schemas/Timestamp'

    ForbiddenContent:
      type: object
      properties:
        action:
          $ref: '#/components/schemas/Action'
        error:
          $ref: '#/components/schemas/ErrorDesc'
        requestId:
          $ref: '#/components/schemas/RequestId'
        timestamp:
          $ref: '#/components/schemas/Timestamp'

    NotFoundContent:
      type: object
      properties:
        action:
          $ref: '#/components/schemas/Action'
        error:
          $ref: '#/components/schemas/ErrorDesc'
        requestId:
          $ref: '#/components/schemas/RequestId'
        timestamp:
          $ref: '#/components/schemas/Timestamp'
paths:
  /signals/{signalBranchPathWithDots}:
    get:
      tags:
        - signals
      summary: "Get signal branch information"
      description:
        Get information for specific signal branch. Branch items are separated by '.' character.<br>
        Response can contain array of other branches and|or signals.
      operationId: getSignalBranchDataWithDots
      parameters:
        - $ref: '#/components/parameters/signalBranchPathWithDots'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequestRsp'
        '403':
          $ref: '#/components/responses/ForbiddenRsp'
        '404':
          $ref: '#/components/responses/NotFoundRsp'

  /signals/{signalBranchPathWithSlashes}:
    get:
      tags:
        - signals
      summary: "Get signal branch information"
      description:
        Get information for specific signal branch. Branch items are separated by '/' character.<br>
        Response can contain array of other branches and|or signals.
      operationId: getSignalBranchDataWithSlashes
      parameters:
        - $ref: '#/components/parameters/signalBranchPathWithSlashes'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequestRsp'
        '403':
          $ref: '#/components/responses/ForbiddenRsp'
        '404':
          $ref: '#/components/responses/NotFoundRsp'

  /signals/{signalBranchPathWithDots}.{signalId}:
    get:
      tags:
        - signals
      summary: "Get specific signal information"
      description: Get complete information for single specific signal
      operationId: "getSingleSignalInformationDots"
      parameters:
        - $ref: '#/components/parameters/signalBranchPathWithDots'
        - $ref: '#/components/parameters/signalId'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequestRsp'
        '403':
          $ref: '#/components/responses/ForbiddenRsp'
        '404':
          $ref: '#/components/responses/NotFoundRsp'

    put:
      tags:
        - signals
      summary: "Set specific signal value"
      description: Set value for single specific signal
      operationId: "putSingleSignalInformationDots"
      parameters:
        - $ref: '#/components/parameters/signalBranchPathWithDots'
        - $ref: '#/components/parameters/signalId'
        - $ref: '#/components/parameters/signalValue'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequestRsp'
        '403':
          $ref: '#/components/responses/ForbiddenRsp'
        '404':
          $ref: '#/components/responses/NotFoundRsp'

  /signals/{signalBranchPathWithSlashes}/{signalId}:
    get:
      tags:
        - signals
      summary: "Get single signal information"
      description: Get complete information for single specific signal
      operationId: getSingleSignalInformationSlashes
      parameters:
        - $ref: '#/components/parameters/signalBranchPathWithSlashes'
        - $ref: '#/components/parameters/signalId'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequestRsp'
        '403':
          $ref: '#/components/responses/ForbiddenRsp'
        '404':
          $ref: '#/components/responses/NotFoundRsp'

    put:
      tags:
        - signals
      summary: "Set single signal information"
      description: Set value for single specific signal
      operationId: putSingleSignalInformationSlashes
      parameters:
        - $ref: '#/components/parameters/signalBranchPathWithSlashes'
        - $ref: '#/components/parameters/signalId'
        - $ref: '#/components/parameters/signalValue'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequestRsp'
        '403':
          $ref: '#/components/responses/ForbiddenRsp'
        '404':
          $ref: '#/components/responses/NotFoundRsp'

  /metadata/{signalBranchPathWithDots}:
    get:
      tags:
        - metadata
      summary: "Get metadata for specified branch"
      description:
        Get metadata information for specific signal branch. Branch items are separated by '.' character.<br>
        Response can contain array of other branches and|or signals.
      operationId: getSignalBranchMetadataWithDots
      parameters:
        - $ref: '#/components/parameters/signalBranchPathWithDots'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequestRsp'

  /metadata/{signalBranchPathWithSlashes}:
    get:
      tags:
        - metadata
      summary: "Get metadata for specified branch"
      description:
        Get metadata information for specific signal branch. Branch items are separated by '/' character.<br>
        Response can contain array of other branches and|or signals.
      operationId: getSignalBranchMetadataWithSlashes
      parameters:
        - $ref: '#/components/parameters/signalBranchPathWithSlashes'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequestRsp'

  /metadata/{signalBranchPathWithDots}.{signalId}:
    get:
      tags:
        - metadata
      summary: "Get metadata for specific signal"
      description: Get metadata information for single specific signal
      operationId: getSingleSignalMetadataInformationDots
      parameters:
        - $ref: '#/components/parameters/signalBranchPathWithDots'
        - $ref: '#/components/parameters/signalId'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequestRsp'

  /metadata/{signalBranchPathWithSlashes}/{signalId}:
    get:
      tags:
        - metadata
      summary: "Get metadata for specific signal"
      description: Get metadata information for single specific signal
      operationId: getSingleSignalMetadataInformationSlashes
      parameters:
        - $ref: '#/components/parameters/signalBranchPathWithSlashes'
        - $ref: '#/components/parameters/signalId'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequestRsp'

  /authorize:
    post:
      tags:
        - authorize
      summary: "Authorize client"
      description:
        Authorize client with JWT token. <br>
        Check <a href="https://jwt.io/">jwt.io</a> for more details on how JWT is generated.
      operationId: postAuthorizeClient
      parameters:
        - $ref: '#/components/parameters/token'
      responses:
        '200':
          $ref: '#/components/responses/SuccessAuthorize'
        '400':
          $ref: '#/components/responses/BadRequestRsp'
        '401':
          $ref: '#/components/responses/UnauthorizedRsp'
