debian-forge-composer/internal/worker/api/openapi.yml

openapi: 3.0.0
info:
  title: OSBuild Composer - Worker
  version: '1'
  description: This is an API for workers to request and handle jobs.
servers:
- url: https://api.openshift.com/api/image-builder-worker/v1
  description: Main (production) server
- url: https://api.stage.openshift.com/api/image-builder-worker/v1
  description: Staging server
- url: /api/image-builder-worker/v1
- url: /api/worker/v1

paths:
  /openapi:
    get:
      operationId: getOpenapi
      summary: Get the openapi spec in json format
      responses:
        '200':
          description: openapi spec in json format
        '500':
          description: Unexpected error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /status:
    get:
      operationId: GetStatus
      summary: status
      description: Simple status handler which returns service status
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '4XX':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '5XX':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /jobs:
    post:
      operationId: RequestJob
      summary: Request a job
      description: Requests a job. This operation blocks until a job is available.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestJobRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestJobResponse'
        '204':
          description: No job was available, try again
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectReference'
        '4XX':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '5XX':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /jobs/{token}:
    parameters:
      - schema:
          type: string
        name: token
        in: path
        required: true
    get:
      operationId: GetJob
      summary: Get running job
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetJobResponse'
        '4XX':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '5XX':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      operationId: UpdateJob
      summary: Update a running job
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateJobRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateJobResponse'
        '4XX':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '5XX':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /jobs/{token}/artifacts/{name}:
    put:
      operationId: UploadJobArtifact
      summary: Upload an artifact
      requestBody:
        content:
          application/octet-stream:
            schema:
              type: string
      parameters:
        - schema:
            type: string
          name: name
          in: path
          required: true
        - schema:
            type: string
          name: token
          in: path
          required: true
      responses:
        '200':
          description: OK
        '4XX':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '5XX':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /errors/{id}:
    get:
      operationId: getError
      summary: Get error description
      description: Get an instance of the error specified by id
      security:
        - Bearer: []
      parameters:
        - in: path
          name: id
          schema:
            type: string
            example: '13'
          required: true
          description: ID of the error
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '4XX':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '5XX':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /workers:
    post:
      operationId: postWorkers
      summary: Create a new worker
      description: |
        Creates a new worker and returns a uuid which should be used in all subsequent calls.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostWorkersRequest'
      responses:
        '201':
          description: Created a new worker
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostWorkersResponse'
  /workers/{worker_id}/status:
    parameters:
      - schema:
          type: string
          format: uuid
        name: worker_id
        in: path
        required: true
    post:
      operationId: postWorkerStatus
      summary: Refresh worker status
      description: |
        Refreshes the heartbeat of the worker, and posts stats that can be used to determine overall
        worker health. Workers that do not respond will not be kept track of after a timeout. If
        dropped workers were running a job, this job will be restarted.
      responses:
        '200':
          description: succesfully updated worker's status

components:
  schemas:
    ObjectReference:
      type: object
      required:
        - id
        - kind
        - href
      properties:
        id:
          type: string
        kind:
          type: string
        href:
          type: string

    Error:
      allOf:
      - $ref: '#/components/schemas/ObjectReference'
      - type: object
        required:
          - code
          - reason
          - operation_id
          - message
        properties:
          code:
            type: string
          reason:
            type: string
          operation_id:
            type: string
          message:
            description: Backward compatibility with workers <= v33, equals reason
            type: string

    StatusResponse:
      allOf:
      - $ref: '#/components/schemas/ObjectReference'
      - type: object
        required:
          - status
        properties:
          status:
            type: string

    RequestJobRequest:
      type: object
      required:
        - types
        - arch
      properties:
        types:
          type: array
          items:
            type: string
        arch:
          type: string
        worker_id:
          type: string
    RequestJobResponse:
      allOf:
      - $ref: '#/components/schemas/ObjectReference'
      - type: object
        required:
          - type
          - location
          - artifact_location
        properties:
          location:
            type: string
          artifact_location:
            type: string
          type:
            type: string
          args:
            x-go-type: json.RawMessage
          dynamic_args:
            type: array
            items:
              x-go-type: json.RawMessage

    GetJobResponse:
      allOf:
      - $ref: '#/components/schemas/ObjectReference'
      - type: object
        required:
          - canceled
        properties:
          canceled:
            type: boolean
    UpdateJobRequest:
      type: object
      required:
        - result
      properties:
        result:
          x-go-type: json.RawMessage
    UpdateJobResponse:
      $ref: '#/components/schemas/ObjectReference'

    PostWorkersRequest:
      type: object
      required:
        - arch
      properties:
        arch:
          type: string
    PostWorkersResponse:
      allOf:
      - $ref: '#/components/schemas/ObjectReference'
      - type: object
        required:
          - worker_id
        properties:
          worker_id:
            type: string
            format: uuid