public.openapi.yaml

---
openapi: 3.0.3
info:
  title: Playbook Dispatcher
  description: Playbook Dispatcher is a service for running Ansible Playbooks on hosts connected via Cloud Connector.
  version: 1.0.0
  contact:
    email: jozef@redhat.com

servers:
  - url: https://cloud.redhat.com
    description: production server
  - url: /
    description: relative path

paths:
  /api/playbook-dispatcher/v1/runs:
    get:
      summary: List Playbook runs
      description: >
        Returns a list of Playbook runs for the given account.
        The list can be filtered using the `filter` parameter.
        The fields returned in the representation can be controller using `fields` parameter.
      operationId: api.runs.list
      parameters:
      - $ref: '#/components/parameters/RunsFilter'
      - $ref: '#/components/parameters/RunsFields'
      - $ref: '#/components/parameters/RunsSortBy'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'

      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Runs'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/playbook-dispatcher/v1/run_hosts:
    get:
      summary: List hosts involved in Playbook runs
      description: >
        Returns a list of objects representing hosts involved in Playbook runs.
        Unless restricted using filters the resources spread across multiple Playbook runs.
        No merging or deduplication is performed by this resource - i.e. if a host X is involved in playbook runs A and B
        then two subresources with exist, one representing X running A and one for B.
      operationId: api.run.hosts.list
      parameters:
      - $ref: '#/components/parameters/RunHostFilter'
      - $ref: '#/components/parameters/RunHostFields'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'

      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunHosts'

        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'

components:
  schemas:
    RunId:
      description: Unique identifier of a Playbook run
      type: string
      format: uuid

    RunRecipient:
      description: Identifier of the host to which a given Playbook is addressed
      type: string
      format: uuid

    RunTimeout:
      description: Amount of seconds after which the run is considered failed due to timeout
      type: integer
      default: 3600
      minimum: 0
      maximum: 604800

    RunCorrelationId:
      description: Unique identifier used to match work request with responses
      type: string

    Account:
      description: Identifier of the tenant
      type: string
      minLength: 1
      maxLength: 10

    OrgId:
      description: Identifier of the tenant
      type: string
      minLength: 1
      maxLength: 10
      example: "5318290"

    PlaybookName:
      description: Human readable name of the playbook run. Used to present the given playbook run in external systems (Satellite).
      type: string
      example: Fix Critical CVEs
      minLength: 1

    WebConsoleUrl:
      description: URL that points to the section of the web console where the user find more information about the playbook run. The field is optional but highly suggested.
      type: string
      format: url
      minLength: 1

    Service:
      description: Service that triggered the given Playbook run
      type: string
      minLength: 1

    Url:
      description: URL hosting the Playbook
      type: string
      format: url

    Labels:
      description: Additional metadata about the Playbook run. Can be used for filtering purposes.
      type: object
      additionalProperties:
        type: string

    RunStatus:
      description: Current status of a Playbook run
      type: string
      enum:
        - running
        - success
        - failure
        - timeout
        - canceled

    CreatedAt:
      description: A timestamp when the entry was created
      type: string
      format: date-time

    UpdatedAt:
      description: A timestamp when the entry was last updated
      type: string
      format: date-time

    Runs:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Run'
        meta:
          $ref: '#/components/schemas/Meta'
        links:
          $ref: '#/components/schemas/Links'
      required:
      - data
      - meta
      - links

    Run:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/RunId'
        account:
          $ref: '#/components/schemas/Account'
        org_id:
          $ref: '#/components/schemas/OrgId'
        recipient:
          $ref: '#/components/schemas/RunRecipient'
        correlation_id:
          $ref: '#/components/schemas/RunCorrelationId'
        name:
          $ref: '#/components/schemas/PlaybookName'
        web_console_url:
          $ref: '#/components/schemas/WebConsoleUrl'
        service:
          $ref: '#/components/schemas/Service'
        url:
          $ref: '#/components/schemas/Url'
        labels:
          $ref: '#/components/schemas/Labels'
        timeout:
          $ref: '#/components/schemas/RunTimeout'
        status:
          $ref: '#/components/schemas/RunStatus'
        created_at:
          $ref: '#/components/schemas/CreatedAt'
        updated_at:
          $ref: '#/components/schemas/UpdatedAt'

    RunHosts:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/RunHost'
        meta:
          $ref: '#/components/schemas/Meta'
        links:
          $ref: '#/components/schemas/Links'
      required:
      - data
      - meta
      - links

    RunHost:
      type: object
      properties:
        host:
          description: Name used to identify a host within Ansible inventory
          type: string
        stdout:
          description: Output produced by running Ansible Playbook on the given host
          type: string
        status:
          $ref: '#/components/schemas/RunStatus'
        run:
          $ref: '#/components/schemas/Run'
        inventory_id:
          type: string
          format: uuid
        links:
          $ref: '#/components/schemas/RunHostLinks'

    RunHostLinks:
      type: object
      properties:
        inventory_host:
          type: string
          nullable: true


    Meta:
      type: object
      additionalProperties: false
      description: Information about returned entities
      properties:
        count:
          type: integer
          description: number of results returned
          example: 50
        total:
          type: integer
          description: total number of results matching the query
          example: 114
      required:
      - count
      - total

    Links:
      type: object
      additionalProperties: false
      required:
      - first
      - last
      properties:
        first:
          type: string
          description: relative link to the first page of the query results
        last:
          type: string
          description: relative link to the last page of the query results
        next:
          type: string
          description: relative link to the next page of the query results
        previous:
          type: string
          description: relative link to the previous page of the query results

    Error:
      type: object
      properties:
        message:
          type: string
      required:
      - message

    RunLabelsNullable:
      type: object
      # this property should not be nullable however it is set so as a workaround for
      # https://github.com/getkin/kin-openapi/issues/293
      nullable: true
      additionalProperties:
        type: string

    StatusNullable:
      type: string
      # this property should not be nullable however it is set so as a workaround for
      # https://github.com/getkin/kin-openapi/issues/293
      # ideally we would reuse '#/components/schemas/RunStatus' here
      nullable: true
      enum:
        - running
        - success
        - failure
        - timeout
        - canceled

    ServiceNullable:
      nullable: true
      # this property should not be nullable however it is set so as a workaround for
      # https://github.com/getkin/kin-openapi/issues/293
      # ideally we would reuse '#/components/schemas/Service' here
      type: string
      minLength: 1

    InventoryIdNullable:
      nullable: true
      type: string
      format: uuid

  parameters:
    RunsFilter:
      description: Allows for filtering based on various criteria
      in: query
      name: filter
      required: false
      style: deepObject
      explode: true
      schema:
        type: object
        properties:
          status:
            $ref: '#/components/schemas/StatusNullable'
          service:
            $ref: '#/components/schemas/ServiceNullable'
          recipient:
            type: string
            # this property should not be nullable however it is set so as a workaround for
            # https://github.com/getkin/kin-openapi/issues/293
            # ideally we would reuse '#/components/schemas/RunRecipient' here
            nullable: true
            format: uuid
          # See ./internal/api/middleware/labelFilters.go
          labels:
            $ref: '#/components/schemas/RunLabelsNullable'

    RunHostFilter:
      description: Allows for filtering based on various criteria
      in: query
      name: filter
      required: false
      style: deepObject
      explode: true
      schema:
        type: object
        properties:
          status:
            $ref: '#/components/schemas/StatusNullable'
          run:
            type: object
            nullable: true
            properties:
              id:
                type: string
                # this property should not be nullable however it is set so as a workaround for
                # https://github.com/getkin/kin-openapi/issues/293
                # ideally we would reuse '#/components/schemas/RunRecipient' here
                nullable: true
                format: uuid
              # See ./internal/api/middleware/labelFilters.go
              service:
                $ref: '#/components/schemas/ServiceNullable'
              labels:
                $ref: '#/components/schemas/RunLabelsNullable'
          inventory_id:
            $ref: '#/components/schemas/InventoryIdNullable'


    RunsFields:
      description: >
        Defines fields to be returned in the response.
      in: query
      name: fields
      required: false
      style: deepObject
      explode: true
      schema:
        type: object
        properties:
          data:
            type: array
            items:
              type: string
              enum:
                - id
                - account
                - recipient
                - correlation_id
                - url
                - labels
                - timeout
                - status
                - service
                - name
                - web_console_url
                - created_at
                - updated_at
            default:
              - id
              - account
              - recipient
              - url
              - labels
              - timeout
              - status

    RunHostFields:
      description: >
        Defines fields to be returned in the response.
      in: query
      name: fields
      required: false
      style: deepObject
      explode: true
      schema:
        type: object
        properties:
          data:
            type: array
            items:
              type: string
              enum:
                - host
                - run
                - status
                - stdout
                - links
                - inventory_id
            default:
              - host
              - status
              - run

    RunsSortBy:
      description: Sort order
      in: query
      name: sort_by
      required: false
      schema:
        type: string
        enum:
          - created_at
          - created_at:asc
          - created_at:desc

    Limit:
      description: Maximum number of results to return
      in: query
      name: limit
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 50

    Offset:
      in: query
      name: offset
      description: Indicates the starting position of the query relative to the complete set of items that match the query
      required: false
      schema:
        type: integer
        minimum: 0
        default: 0


  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    Forbidden:
      description: Access to the given resource is not allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'