OPENAPI_DOC.yml

---
openapi: 3.0.3
info:
  description: PlaceOS Build API. Performs driver compilation, retrieval and storage
    on S3
  title: build-api
  version: 1.1.0
paths:
  /api/build/v1:
    get:
      tags:
      - Driver
      operationId: PlaceOS::Api::Driver_index
      parameters: []
      responses:
        200:
          description: OK
        401:
          description: Unauthorized
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__CommonError'
        406:
          description: Not Acceptable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__CommonError'
        415:
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__ContentError'
        422:
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__ParameterError'
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__ParameterError'
  /api/build/v1/version:
    get:
      summary: returns the build details of the service
      tags:
      - Driver
      operationId: PlaceOS::Api::Driver_version
      parameters: []
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NamedTuple_version__String__build_time__String__commit__String__service__String_'
        401:
          description: Unauthorized
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__CommonError'
        406:
          description: Not Acceptable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__CommonError'
        415:
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__ContentError'
        422:
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__ParameterError'
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__ParameterError'
  /api/build/v1/{arch}/compiled/{file_name}:
    get:
      summary: If requested driver is compiled and available in S3, returns 200 with
        json response with size, md5, modified-time, pre-signed url details
      description: 'If requested driver is compiled and available in S3, returns 200
        with json response with size, md5, modified-time, pre-signed url details

        else returns 404'
      tags:
      - Driver
      operationId: PlaceOS::Api::Driver_compiled
      parameters:
      - name: arch
        in: path
        description: the system architecture, defaults to architecutre of system where
          this service is running
        example: amd64 | arm64
        required: true
        schema:
          type: string
      - name: file_name
        in: path
        description: the name of the driver file in the repository
        example: drivers/place/meet.cr
        required: true
        schema:
          type: string
      - name: url
        in: query
        description: URL for a git repository
        example: https://github.com/placeOS/drivers
        required: true
        schema:
          type: string
      - name: branch
        in: query
        description: Branch to return driver binary for, defaults to master
        example: main
        required: false
        schema:
          type: string
          nullable: true
      - name: commit
        in: query
        description: the commit hash of the driver to check is compiled
        example: e901494
        required: true
        schema:
          type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/_PlaceOS__Api__S3__LinkData___Nil_'
        401:
          description: Unauthorized
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__CommonError'
        406:
          description: Not Acceptable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__CommonError'
        415:
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__ContentError'
        422:
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__ParameterError'
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__ParameterError'
  /api/build/v1/metadata/{file_name}:
    get:
      summary: If requested driver is compiled and available in S3, returns 200 with
        metadata json
      description: 'If requested driver is compiled and available in S3, returns 200
        with metadata json

        else returns 404'
      tags:
      - Driver
      operationId: PlaceOS::Api::Driver_metadata
      parameters:
      - name: file_name
        in: path
        description: the name of the driver file in the repository
        example: drivers/place/meet.cr
        required: true
        schema:
          type: string
      - name: url
        in: query
        description: URL for a git repository
        example: https://github.com/placeOS/drivers
        required: true
        schema:
          type: string
      - name: branch
        in: query
        description: Branch to return driver binary for, defaults to master
        example: main
        required: false
        schema:
          type: string
          nullable: true
      - name: commit
        in: query
        description: the commit hash of the driver to check is compiled, defaults
          to latest commit on branch
        example: e901494362f6859100b8f3
        required: true
        schema:
          type: string
      - name: arch
        in: query
        required: false
        schema:
          type: string
          nullable: true
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/_String___Nil_'
        401:
          description: Unauthorized
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__CommonError'
        406:
          description: Not Acceptable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__CommonError'
        415:
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__ContentError'
        422:
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__ParameterError'
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__ParameterError'
  /api/build/v1/defaults/{file_name}:
    get:
      summary: If requested driver is compiled and available in S3, returns 200 with
        defaults json
      description: 'If requested driver is compiled and available in S3, returns 200
        with defaults json

        else returns 404'
      tags:
      - Driver
      operationId: PlaceOS::Api::Driver_defaults
      parameters:
      - name: file_name
        in: path
        description: the name of the driver file in the repository
        example: drivers/place/meet.cr
        required: true
        schema:
          type: string
      - name: url
        in: query
        description: URL for a git repository
        example: https://github.com/placeOS/drivers
        required: true
        schema:
          type: string
      - name: branch
        in: query
        description: Branch to return driver binary for, defaults to master
        example: main
        required: false
        schema:
          type: string
          nullable: true
      - name: commit
        in: query
        description: the commit hash of the driver to check is compiled, defaults
          to latest commit on branch
        example: e901494362f6859100b8f3
        required: true
        schema:
          type: string
      - name: arch
        in: query
        required: false
        schema:
          type: string
          nullable: true
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/_String___Nil_'
        401:
          description: Unauthorized
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__CommonError'
        406:
          description: Not Acceptable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__CommonError'
        415:
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__ContentError'
        422:
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__ParameterError'
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__ParameterError'
  /api/build/v1/{arch}/{file_name}:
    post:
      summary: Async endpoint.
      description: 'Async endpoint.

        Upon receiving driver compilation request, it will return HTTP Status code
        202 (Accepted) along with TaskStatus object, client should follow link provided
        in header field

        Content-Location to track the status of this request.'
      tags:
      - Driver
      operationId: PlaceOS::Api::Driver_build
      parameters:
      - name: arch
        in: path
        description: the system architecture, defaults to architecutre of system where
          this service is running
        example: amd64 | arm64
        required: true
        schema:
          type: string
      - name: file_name
        in: path
        description: the name of the driver file in the repository
        example: drivers/place/meet.cr
        required: true
        schema:
          type: string
      - name: url
        in: query
        description: URL for a git repository
        example: https://github.com/placeOS/drivers
        required: true
        schema:
          type: string
      - name: branch
        in: query
        description: Branch to return commits for, defaults to master
        example: main
        required: true
        schema:
          type: string
      - name: commit
        in: query
        description: the commit hash of the driver to check is compiled
        example: e901494
        required: true
        schema:
          type: string
      - name: force
        in: query
        description: Whether to re-compile driver using the latest shards? default
          is false
        example: "true"
        required: false
        schema:
          type: boolean
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__TaskStatus'
        401:
          description: Unauthorized
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__CommonError'
        406:
          description: Not Acceptable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__CommonError'
        415:
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__ContentError'
        422:
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__ParameterError'
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__ParameterError'
  /api/build/v1/{arch}/task/{id}:
    get:
      summary: Returns the status of driver compilation request submitted via POST
        operation.
      description: 'Returns the status of driver compilation request submitted via
        POST operation.

        Still processing: Returns reponse code 200 (OK) and a TaskStatus object representing
        the status

        Compilation completed: Returns response code 303 (See Other) and a Location
        header containing a URI of the resource to fetch compiled driver binary

        Compilation Failure: Returns response code 200 (OK) and a TaskStatus object
        representing the status and failure message/reason.

        Returns 404 if no such task exists'
      tags:
      - Driver
      operationId: PlaceOS::Api::Driver_task_status
      parameters:
      - name: arch
        in: path
        description: the system architecture, defaults to architecutre of system where
          this service is running
        example: amd64 | arm64
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Submitted Job ID returned by POST request
        required: true
        schema:
          type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/_PlaceOS__Api__TaskStatus___Nil_'
        401:
          description: Unauthorized
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__CommonError'
        406:
          description: Not Acceptable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__CommonError'
        415:
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__ContentError'
        422:
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__ParameterError'
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__ParameterError'
  /api/build/v1/monitor:
    get:
      summary: Job monitor endpoint. Provides a list of requested state Jobs
      tags:
      - Monitor
      operationId: PlaceOS::Api::Monitor_monitor
      parameters:
      - name: state
        in: query
        description: state of job to return. One of [pending,running,cancelled error,done].
          Defaults to 'pending'
        example: pending
        required: false
        schema:
          type: string
          enum:
          - pending
          - running
          - cancelled
          - error
          - done
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PlaceOS__Api__TaskStatus'
        401:
          description: Unauthorized
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__CommonError'
        406:
          description: Not Acceptable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__CommonError'
        415:
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__ContentError'
        422:
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__ParameterError'
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__ParameterError'
  /api/build/v1/cancel/{job}:
    delete:
      tags:
      - Monitor
      operationId: PlaceOS::Api::Monitor_cancel
      parameters:
      - name: job
        in: path
        description: ID of previously submitted compilation job
        required: true
        schema:
          type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/_String___Nil_'
        401:
          description: Unauthorized
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__CommonError'
        406:
          description: Not Acceptable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__CommonError'
        415:
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__ContentError'
        422:
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__ParameterError'
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceOS__Api__Application__ParameterError'
components:
  schemas:
    NamedTuple_version__String__build_time__String__commit__String__service__String_:
      type: object
      properties:
        version:
          type: string
        build_time:
          type: string
        commit:
          type: string
        service:
          type: string
      required:
      - version
      - build_time
      - commit
      - service
    _PlaceOS__Api__S3__LinkData___Nil_:
      type: object
      properties:
        size:
          type: integer
          format: Int64
        md5:
          type: string
        modified:
          type: string
          format: date-time
        url:
          type: string
        link_expiry:
          type: string
          format: date-time
      required:
      - size
      - md5
      - modified
      - url
      - link_expiry
      nullable: true
    _String___Nil_:
      type: string
      nullable: true
    PlaceOS__Api__TaskStatus:
      type: object
      properties:
        state:
          type: string
          enum:
          - pending
          - running
          - cancelled
          - error
          - done
        id:
          type: string
        message:
          type: string
        driver:
          type: string
        repo:
          type: string
        branch:
          type: string
        commit:
          type: string
        timestamp:
          type: string
          format: date-time
      required:
      - state
      - id
      - message
      - driver
      - repo
      - branch
      - commit
      - timestamp
    _PlaceOS__Api__TaskStatus___Nil_:
      type: object
      properties:
        state:
          type: string
          enum:
          - pending
          - running
          - cancelled
          - error
          - done
        id:
          type: string
        message:
          type: string
        driver:
          type: string
        repo:
          type: string
        branch:
          type: string
        commit:
          type: string
        timestamp:
          type: string
          format: date-time
      required:
      - state
      - id
      - message
      - driver
      - repo
      - branch
      - commit
      - timestamp
      nullable: true
    PlaceOS__Api__Application__CommonError:
      type: object
      properties:
        error:
          type: string
          nullable: true
        backtrace:
          type: array
          items:
            type: string
          nullable: true
    PlaceOS__Api__Application__ContentError:
      type: object
      properties:
        error:
          type: string
        accepts:
          type: array
          items:
            type: string
          nullable: true
      required:
      - error
      description: Provides details on available data formats
    PlaceOS__Api__Application__ParameterError:
      type: object
      properties:
        error:
          type: string
        parameter:
          type: string
          nullable: true
        restriction:
          type: string
          nullable: true
      required:
      - error
      description: Provides details on which parameter is missing or invalid