private.openapi.yaml

---
openapi: 3.0.3
info:
  title: Playbook Dispatcher Internal API
  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: /
    description: relative path

paths:
  /internal/dispatch:
    post:
      summary: Dispatch Playbooks
      description: Dispatches Playbooks using Cloud Connector and stores corresponding run records.
      operationId: api.internal.runs.create
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/RunInput'
              minItems: 1
              maxItems: 50
      responses:
        '207':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunsCreated'
        '400':
          $ref: '#/components/responses/BadRequest'

  /internal/version:
    get:
      summary: Get Version
      description: Indicates the git revision the API was built from.
      operationId: api.internal.version
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Version'

  /internal/v2/recipients/status:
    post:
      summary: Obtain connection status of recipient(s)
      description: Indicates whether the given recipient(s) are available
      operationId: api.internal.v2.recipients.status
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/RecipientWithOrg'
              minItems: 1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RecipientStatus'
        '400':
          $ref: '#/components/responses/BadRequest'

  /internal/v2/dispatch:
    post:
      summary: Dispatch Playbooks
      description: Dispatches Playbooks using Cloud Connector and stores corresponding run records.
      operationId: api.internal.v2.runs.create
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/RunInputV2'
              minItems: 1
              maxItems: 50
      responses:
        '207':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunsCreated'

  /internal/v2/cancel:
    post:
      summary: Cancel Playbook Runs
      description: Cancels Playbook Runs using Cloud Connector
      operationId: api.internal.v2.runs.cancel
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items: 
                $ref: '#/components/schemas/CancelInputV2'
              minItems: 1
              maxItems: 50
      responses:
        '207':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunsCanceled'
        '400':
          $ref: '#/components/responses/BadRequest'

  /internal/v2/connection_status:
    post:
      summary: Obtain Connection Status of recipient(s) based on a list of host IDs
      description: Builds list of recipient(s) and indicates whether the given recipient(s) are available
      operationId: api.internal.highlevel.connection.status
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HostsWithOrgId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HighLevelRecipientStatus'
        '400':
          $ref: '#/components/responses/BadRequest'

components:
  schemas:
    RunInput:
      type: object
      properties:
        recipient:
          $ref: './public.openapi.yaml#/components/schemas/RunRecipient'
        account:
          $ref: './public.openapi.yaml#/components/schemas/Account'
        url:
          $ref: './public.openapi.yaml#/components/schemas/Url'
        labels:
          $ref: './public.openapi.yaml#/components/schemas/Labels'
        timeout:
          $ref: './public.openapi.yaml#/components/schemas/RunTimeout'
        hosts:
          $ref: '#/components/schemas/RunInputHosts'
      required:
      - recipient
      - account
      - url

    RunInputV2:
      type: object
      properties:
        recipient:
          $ref: './public.openapi.yaml#/components/schemas/RunRecipient'
        org_id:
          $ref: './public.openapi.yaml#/components/schemas/OrgId'
        principal:
          $ref: '#/components/schemas/Principal'
        url:
          $ref: './public.openapi.yaml#/components/schemas/Url'
        name:
          $ref: './public.openapi.yaml#/components/schemas/PlaybookName'
        web_console_url:
          $ref: './public.openapi.yaml#/components/schemas/WebConsoleUrl'
        labels:
          $ref: './public.openapi.yaml#/components/schemas/Labels'
        timeout:
          $ref: './public.openapi.yaml#/components/schemas/RunTimeout'
        hosts:
          $ref: '#/components/schemas/RunInputHosts'
        recipient_config:
          $ref: '#/components/schemas/RecipientConfig'
      required:
      - recipient
      - org_id
      - principal
      - url
      - name

    CancelInputV2:
      type: object
      properties:
        run_id:
          $ref: './public.openapi.yaml#/components/schemas/RunId'
        org_id:
          $ref: '#/components/schemas/OrgId'
        principal:
          $ref: '#/components/schemas/Principal'
      required:
      - run_id
      - org_id
      - principal
    
    RunCanceled:
      type: object
      properties:
        run_id:
          $ref: './public.openapi.yaml#/components/schemas/RunId'
        code:
          type: integer
          example: 202
          description: status code of the request
      required:
      - code
      - run_id

    RunInputHosts:
      type: array
      description: |
        Optionally, information about hosts involved in the Playbook run can be provided.
        This information is used to pre-allocate run_host resources.
        Moreover, it can be used to create a connection between a run_host resource and host inventory.
      items:
        type: object
        properties:
          ansible_host:
            type: string
            description: |
              Host name as known to Ansible inventory.
              Used to identify the host in status reports.
            example: localhost
            minLength: 1
          inventory_id:
            type: string
            format: uuid
            description: Inventory id of the given host
            example: ffb47020-a6fd-484d-80b5-da00a4a30bf2

    RunCreated:
      type: object
      properties:
        code:
          type: integer
          example: 201
          description: status code of the request
        message: 
          type: string
          example: "Unexpected error during processing"
          description: Error Message
        id:
          $ref: './public.openapi.yaml#/components/schemas/RunId'
      required:
      - code

    RecipientConfig:
      description: recipient-specific configuration options
      type: object
      properties:
        sat_id:
          description: Identifier of the Satellite instance in the uuid v4/v5 format
          type: string
          format: sat-id-uuid
          example: aa3b1faa-56f3-4d14-8258-615d11e20060
        sat_org_id:
          description: Identifier of the organization within Satellite
          type: string
          example: "12345"
          minLength: 1

    RunsCanceled:
      type: array
      items:
        $ref: '#/components/schemas/RunCanceled'

    RunsCreated:
      type: array
      items:
        $ref: '#/components/schemas/RunCreated'

    RecipientWithOrg:
      type: object
      properties:
        recipient:
          $ref: './public.openapi.yaml#/components/schemas/RunRecipient'
        org_id:
          $ref: '#/components/schemas/OrgId'
      required:
      - recipient
      - org_id

    RecipientStatus:
      allOf:
      - $ref: '#/components/schemas/RecipientWithOrg'
      - type: object
        properties:
          connected:
            type: boolean
            description: Indicates whether a connection is established with the recipient
        required:
        - connected

    HostsWithOrgId:
      type: object
      properties:
        org_id:
          $ref: '#/components/schemas/OrgId'
        hosts:
          type: array
          items:
            description: Identifies a record of the Host-Inventory service
            type: string
            minLength: 1
      required:
      - org_id
      - hosts

    RecipientWithConnectionInfo:
      type: object
      properties:
        recipient:
          $ref: './public.openapi.yaml#/components/schemas/RunRecipient'
        org_id:
          $ref: '#/components/schemas/OrgId'
        sat_id:
          $ref: '#/components/schemas/SatelliteId'
        sat_org_id:
          $ref: '#/components/schemas/SatelliteOrgId'
        recipient_type:
          $ref: '#/components/schemas/RecipientType'
        systems:
          type: array
          items:
            $ref: '#/components/schemas/HostId'
        status:
          description: Indicates the current run status of the recipient
          type: string
          enum: [connected, disconnected, rhc_not_configured]
      required:
      - recipient
      - org_id
      - recipient_type
      - sat_id
      - sat_org_id
      - systems
      - status


    HighLevelRecipientStatus:
      type: array
      items:
        $ref: '#/components/schemas/RecipientWithConnectionInfo'

    HostId:
      description: Identifies a record of the Host-Inventory service
      type: string
      minLength: 1

    SatelliteId:
      description: Identifier of the Satellite instance in the uuid v4/v5 format
      type: string
      format: sat-id-uuid
      example: aa3b1faa-56f3-4d14-8258-615d11e20060
    
    SatelliteOrgId:
      description: Identifier of the organization within Satellite
      type: string
      example: "12345"

    RecipientType:
      description: Identifies the type of recipient [Satellite, Direct Connected, None]
      type: string
      enum: [satellite, directConnect, none]
      minLength: 1

    OrgId:
      description: Identifies the organization that the given resource belongs to
      type: string
      minLength: 1
      maxLength: 10

    Principal:
      description: Username of the user interacting with the service
      type: string
      example: jharting
      minLength: 1

    Version:
      description: Version of the API
      type: string
      example: v2
      minLength: 1

    Error:
      type: object
      properties:
        message:
          type: string
          description: Human readable error message
          example: Minimum string length is 1
      required:
      - message

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