api.spec.yaml

openapi: 3.0.0
info:
  description: REST interface for the Insights Platform Host Inventory application.
  version: 1.0.0
  title: Insights Host Inventory REST Interface
paths:
  /hosts:
    get:
      operationId: api.host.get_host_list
      tags:
        - hosts
      summary: Read the entire list of hosts
      description: Read the entire list of all hosts available to the account.
      security:
        - ApiKeyAuth: []
      parameters:
        - in: query
          name: display_name
          schema:
            type: string
          description: A part of a searched host’s display name.
          required: false
        - in: query
          name: fqdn
          schema:
            type: string
          description: Filter by a host's FQDN
          required: false
        - in: query
          name: hostname_or_id
          schema:
            type: string
          description: 'Search for a host by display_name, fqdn, id'
          required: false
        - in: query
          name: insights_id
          schema:
            type: string
            format: uuid
          description: Search for a host by insights_id
          required: false
        - in: query
          name: branch_id
          schema:
            type: string
          description: Filter by branch_id
          required: false
        - $ref: '#/components/parameters/perPageParam'
        - $ref: '#/components/parameters/pageParam'
      responses:
        '200':
          description: Successfully read the hosts list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HostQueryOutput'
    post:
      operationId: api.host.add_host_list
      tags:
        - hosts
      summary: Create/update multiple host and add them to the host list
      description: >-
        Create a new host and add it to the host list or update an existing
        hosts. A host is updated if there is already one with the same
        canonicals facts and belonging to the same account.
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      requestBody:
        description: A list of host objects to be added to the host list
        required: true
        content:
          application/json:
            schema:
              x-body-name: host_list
              type: array
              items:
                $ref: '#/components/schemas/CreateHostIn'
      responses:
        '207':
          description: Successfully created a host.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkHostOut'
              examples:
                update:
                  value:
                    status: 200
                    host: Host details
                create:
                  value:
                    status: 201
                    host: Host details
                error:
                  value:
                    status: 400
                    title: Invalid Request
                    detail: Could not process request
                    host: Input host data
        '400':
          description: Invalid request.
  '/hosts/{host_id_list}':
    get:
      tags:
        - hosts
      summary: Find hosts by their IDs
      description: Find one or more hosts by their ID.
      operationId: api.host.get_host_by_id
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: host_id_list
          description: A comma separated list of host IDs.
          required: true
          schema:
            type: array
            items:
              type: string
              format: uuid
        - in: query
          name: branch_id
          schema:
            type: string
          description: Filter by branch_id
          required: false
        - $ref: '#/components/parameters/perPageParam'
        - $ref: '#/components/parameters/pageParam'
      responses:
        '200':
          description: Successfully searched for hosts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HostQueryOutput'
        '400':
          description: Invalid request.
        '404':
          description: Host not found.
    patch:
      tags:
        - hosts
      summary: Update a host
      description: Update a host
      operationId: api.host.patch_by_id
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: host_id_list
          description: A host ID
          required: true
          schema:
            type: array
            items:
              type: string
              format: uuid
        - in: query
          name: branch_id
          schema:
            type: string
          description: Filter by branch_id
          required: false
      requestBody:
        description: A group of fields to be updated on the host
        required: true
        content:
          application/json:
            schema:
              x-body-name: host_data
              $ref: '#/components/schemas/PatchHostIn'
      responses:
        '200':
          description: Successfully updated the host.
        '400':
          description: Invalid request.
        '404':
          description: Host not found.
  '/hosts/{host_id_list}/facts/{namespace}':
    patch:
      tags:
        - hosts
      summary: Merge facts under a namespace
      description: Merge one or multiple hosts facts under a namespace.
      operationId: api.host.merge_facts
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: host_id_list
          description: IDs of the hosts that own the facts to be merged.
          required: true
          schema:
            type: array
            items:
              type: string
        - in: path
          name: namespace
          description: A namespace of the merged facts.
          required: true
          schema:
            type: string
      requestBody:
        description: A dictionary with the new facts to merge with the original ones.
        required: true
        content:
          application/json:
            schema:
              x-body-name: fact_dict
              $ref: '#/components/schemas/Facts'
      responses:
        '200':
          description: Successfully merged facts.
        '400':
          description: Invalid request.
        '404':
          description: Host or namespace not found.
    put:
      tags:
        - hosts
      summary: Replace facts under a namespace
      description: Replace facts under a namespace
      security:
        - ApiKeyAuth: []
      operationId: api.host.replace_facts
      parameters:
        - in: path
          name: host_id_list
          description: IDs of the hosts that own the facts to be replaced.
          required: true
          schema:
            type: array
            items:
              type: string
        - in: path
          name: namespace
          description: A namespace of the merged facts.
          required: true
          schema:
            type: string
      requestBody:
        description: A dictionary with the new facts to replace the original ones.
        required: true
        content:
          application/json:
            schema:
              x-body-name: fact_dict
              $ref: '#/components/schemas/Facts'
      responses:
        '200':
          description: Successfully replaced facts.
        '400':
          description: Invalid request.
        '404':
          description: Host or namespace not found.
  '/hosts/{host_id_list}/system_profile':
    get:
      tags:
        - hosts
      summary: Return one or more hosts system profile
      description: Find one or more hosts by their ID and return the id and system profile
      operationId: api.host.get_host_system_profile_by_id
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: host_id_list
          description: A comma separated list of host IDs.
          required: true
          schema:
            type: array
            items:
              type: string
              format: uuid
        - $ref: '#/components/parameters/perPageParam'
        - $ref: '#/components/parameters/pageParam'
      responses:
        '200':
          description: Successfully searched for hosts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemProfileByHostOut'
        '400':
          description: Invalid request.
        '404':
          description: Host not found.
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      x-bearerInfoFunc: app.auth.bearer_token_handler
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-rh-identity
      description: >-
        Base64-encoded JSON identity header provided by 3Scale. Contains an
        account number of the user issuing the request. Format of the JSON:
        {"identity": {"account_number": "12345678"}}
      x-apikeyInfoFunc: app.auth.authentication_header_handler
  parameters:
    pageParam:
      name: page
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
      description: A page number of the items to return.
    perPageParam:
      name: per_page
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
      description: A number of items to return per page.
  schemas:
    BulkHostOut:
      type: object
      properties:
        total:
          type: integer
          description: Total number of items in the "data" list.
        errors:
          type: integer
          description: Number of items in the "data" list that contain errors.
        data:
          type: array
          items:
            $ref: '#/components/schemas/BulkHostOutDetails'
          description: 'List of hosts that were created, updated or failed to be processed.'
    BulkHostOutDetails:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code of the results of the host create/update process
        host:
          $ref: '#/components/schemas/CreateHostOut'
        title:
          type: string
          description: Short description of why a host failed to be created or updated.
        detail:
          type: string
          description: Details about why a host failed to be created or updated.
    Facts:
      title: Host facts
      description: A set of string facts about a host.
      type: object
      example:
        fact1: value1
        fact2: value2
    FactSet:
      title: Host facts under a namespace
      description: A set of string facts belonging to a single namespace.
      properties:
        namespace:
          type: string
          minLength: 1
          description: A namespace the facts belong to.
        facts:
          type: object
          description: The facts themselves.
          example:
            fact1: value1
            fact2: value2
      required:
        - namespace
        - facts
    CreateHostIn:
      title: Host data
      description: >-
        Data of a single host belonging to an account. Represents the hosts
        without its Inventory metadata.
      type: object
      required:
        - account
      properties:
        display_name:
          description: >-
            A host’s human-readable display name, e.g. in a form of a domain
            name.
          type: string
          example: host1.mydomain.com
        ansible_host:
          description: >-
            The ansible host name for remediations
          type: string
          example: host1.mydomain.com
        account:
          description: A Red Hat Account number that owns the host.
          type: string
          example: '000102'
        insights_id:
          description: >-
            An ID defined in /etc/insights-client/machine-id. This field is
            considered a canonical fact.
          type: string
          example: 3f01b55457674041b75e41829bcee1dc
        rhel_machine_id:
          description: >-
            A Machine ID of a RHEL host.  This field is considered to be a
            canonical fact.
          type: string
          example: 3f01b55457674041b75e41829bcee1dc
        subscription_manager_id:
          description: >-
            A Red Hat Subcription Manager ID of a RHEL host.  This field is
            considered to be a canonical fact.
          type: string
          example: 3f01b55457674041b75e41829bcee1dc
        satellite_id:
          description: >-
            A Red Hat Satellite ID of a RHEL host.  This field is considered to
            be a canonical fact.
          type: string
          example: 3f01b55457674041b75e41829bcee1dc
        bios_uuid:
          description: >-
            A UUID of the host machine BIOS.  This field is considered to be a
            canonical fact.
          type: string
          example: 3f01b55457674041b75e41829bcee1dc
        ip_addresses:
          description: >-
            Host’s network IP addresses.  This field is considered to be a
            canonical fact.
          type: array
          items:
            type: string
          example:
            - 10.10.0.1
            - 10.0.0.2
        fqdn:
          description: >-
            A host’s Fully Qualified Domain Name.  This field is considered to
            be a canonical fact.
          type: string
          example: my.host.example.com
        mac_addresses:
          description: >-
            Host’s network interfaces MAC addresses.  This field is considered
            to be a canonical fact.
          type: array
          items:
            type: string
          example:
            - 'c2:00:d0:c8:61:01'
        external_id:
          description: >-
            Host’s reference in the external source e.g. AWS EC2, Azure,
            OpenStack, etc. This field is considered to be a canonical fact.
          type: string
          example: i-05d2313e6b9a42b16
        facts:
          description: A set of facts belonging to the host.
          type: array
          items:
            $ref: '#/components/schemas/FactSet'
        system_profile:
          $ref: '#/components/schemas/SystemProfileIn'
    CreateHostOut:
      title: Create Host Out
      description: >-
        Data of a single host belonging to an account. Represents the hosts
        without its Inventory metadata.
      type: object
      required:
        - account
      properties:
        display_name:
          description: >-
            A host’s human-readable display name, e.g. in a form of a domain
            name.
          type: string
          example: host1.mydomain.com
          nullable: true
        ansible_host:
          description: >-
            The ansible host name for remediations
          type: string
          example: host1.mydomain.com
          nullable: true
        account:
          description: A Red Hat Account number that owns the host.
          type: string
          example: '000102'
        insights_id:
          description: >-
            An ID defined in /etc/insights-client/machine-id. This field is
            considered a canonical fact.
          type: string
          example: 3f01b55457674041b75e41829bcee1dc
          nullable: true
        rhel_machine_id:
          description: >-
            A Machine ID of a RHEL host.  This field is considered to be a
            canonical fact.
          type: string
          example: 3f01b55457674041b75e41829bcee1dc
          nullable: true
        subscription_manager_id:
          description: >-
            A Red Hat Subcription Manager ID of a RHEL host.  This field is
            considered to be a canonical fact.
          type: string
          example: 3f01b55457674041b75e41829bcee1dc
          nullable: true
        satellite_id:
          description: >-
            A Red Hat Satellite ID of a RHEL host.  This field is considered to
            be a canonical fact.
          type: string
          example: 3f01b55457674041b75e41829bcee1dc
          nullable: true
        bios_uuid:
          description: >-
            A UUID of the host machine BIOS.  This field is considered to be a
            canonical fact.
          type: string
          example: 3f01b55457674041b75e41829bcee1dc
          nullable: true
        ip_addresses:
          description: >-
            Host’s network IP addresses.  This field is considered to be a
            canonical fact.
          type: array
          items:
            type: string
          nullable: true
          example:
            - 10.10.0.1
            - 10.0.0.2
        fqdn:
          description: >-
            A host’s Fully Qualified Domain Name.  This field is considered to
            be a canonical fact.
          type: string
          example: my.host.example.com
          nullable: true
        mac_addresses:
          description: >-
            Host’s network interfaces MAC addresses.  This field is considered
            to be a canonical fact.
          type: array
          items:
            type: string
          nullable: true
          example:
            - 'c2:00:d0:c8:61:01'
        external_id:
          description: >-
            Host’s reference in the external source e.g. AWS EC2, Azure,
            OpenStack, etc. This field is considered to be a canonical fact.
          type: string
          nullable: true
          example: i-05d2313e6b9a42b16
        id:
          description: >-
            A durable and reliable platform-wide host identifier. Applications
            should use this identifier to reference hosts.
          type: string
          example: 3f01b55457674041b75e41829bcee1dc
        created:
          description: A timestamp when the entry was created.
          type: string
          format: date-time
        updated:
          description: A timestamp when the entry was last updated.
          type: string
          format: date-time
        facts:
          description: A set of facts belonging to the host.
          type: array
          items:
            $ref: '#/components/schemas/FactSet'
    HostOut:
      title: A Host Inventory entry
      description: A database entry representing a single host with its Inventory metadata.
      allOf:
        - $ref: '#/components/schemas/CreateHostOut'
        - type: object
          properties:
            facts:
              description: A set of facts belonging to the host.
              type: array
              items:
                $ref: '#/components/schemas/FactSet'
    HostQueryOutput:
      title: A Host Inventory query result
      description: >-
        A paginated host search query result with host entries and their
        Inventory metadata.
      type: object
      required:
        - count
        - page
        - per_page
        - total
        - results
      properties:
        count:
          description: A number of entries on the current page.
          type: integer
        page:
          description: A current page number.
          type: integer
        per_page:
          description: A page size – a number of entries per single page.
          type: integer
        total:
          description: A total count of the found entries.
          type: integer
        results:
          description: Actual host search query result entries.
          type: array
          items:
            $ref: '#/components/schemas/HostOut'
    SystemProfileByHostOut:
      title: A host system profile query result
      description: Structure of the output of the host system profile query
      type: object
      required:
        - count
        - page
        - per_page
        - total
        - results
      properties:
        count:
          description: A number of entries on the current page.
          type: integer
        page:
          description: A current page number.
          type: integer
        per_page:
          description: A page size – a number of entries per single page.
          type: integer
        total:
          description: A total count of the found entries.
          type: integer
        results:
          description: Actual host search query result entries.
          type: array
          items:
            $ref: '#/components/schemas/HostSystemProfileOut'
    HostSystemProfileOut:
      title: Structure of an individual host system profile output
      description: Individual host record that contains only the host id and system profile
      properties:
        id:
          type: string
        system_profile:
          $ref: '#/components/schemas/SystemProfileIn'
    DiskDevice:
      title: Disk Device
      description: Representation of one mounted device
      properties:
        device:
          example:
            device:
              summary: device example
              value: "/dev/fdd0"
          type: string
        label:
          description: user-defined mount label
          type: string
        options:
          description: mount options
          example:
            options:
              summary: Options example
              value: {"uid": "0", "ro": true}
          type: object
          properties:
            name:
              type: string
            value:
              type: string
        mount_point:
          description: mount point
          example:
            mountpoint:
              summary: mount point example
              value: "/mnt/remote_nfs_share"
          type: string
        type:
          description: mount type
          example:
            mounttype:
              summary: mount type example
              value: "ext3"
          type: string
    YumRepo:
      title: Yum Repository
      description: Representation of one yum repository
      properties:
        name:
          type: string
        gpgcheck:
          type: boolean
        enabled:
          type: boolean
        baseurl:
          type: string
          format: uri
    InstalledProduct:
      title: Installed Product
      description: Representation of one installed product
      properties:
        name:
          type: string
        id:
          description: the product ID
          example:
            product_id:
              summary: product ID example
              value: "71"
          type: string
        status:
          description: subscription status for product
          example:
            status:
              summary: status example
              value: "Subscribed"
          type: string
    NetworkInterface:
      title: Network Interface
      description: Representation of one network interface
      properties:
        ipv4_addresses:
          type: array
          items:
            type: string
            format: ipv4
        ipv6_addresses:
          type: array
          items:
            type: string
            format: ipv6
        mtu:
          description: MTU
          type: integer
        mac_address:
          description: MAC address
          example:
            mac_colons:
              summary: mac address with colons
              value: "00:00:00:00:00:00"
            mac_hex:
              summary: mac address
              value: "000000000000"
          type: string
        name:
          description: name of interface
          type: string
          example:
            eth0:
              summary: eth0 example
              value: "eth0"
        state:
          description: interface state
          type: string
          example:
            up:
              summary: up example
              value: "UP"
            down:
              summary: down example
              value: "DOWN"
            unknown:
              summary: unknown example
              value: "UNKNOWN"
        type:
          description: interface type
          type: string
          example:
            ether:
              summary: ether example
              value: "ether"
            loop:
              summary: loopback example
              value: "loopback"
    SystemProfileIn:
      title: System profile fields
      description: Representation of the system profile fields
      type: object
      properties:
        number_of_cpus:
          type: integer
        number_of_sockets:
          type: integer
        cores_per_socket:
          type: integer
        system_memory_bytes:
          type: integer
        infrastructure_type:
          type: string
        infrastructure_vendor:
          type: string
        network_interfaces:
          type: array  # techincally a set, ordering is not important
          items:
            $ref: '#/components/schemas/NetworkInterface'
        disk_devices:
          type: array  # techincally a set, ordering is not important
          items:
            $ref: '#/components/schemas/DiskDevice'
        bios_vendor:
          type: string
        bios_version:
          type: string
        bios_release_date:
          type: string
        cpu_flags:
          items:
            type: string
          type: array
        os_release:
          type: string
        os_kernel_version:
          type: string
        arch:
          type: string
        kernel_modules:
          type: array
          items:
            type: string
        last_boot_time:
          type: string
          format: date-time
        running_processes:
          type: array  # techincally a set, ordering is not important
          items:
            description: a single running process. This will be truncated to 1000 characters when saved.
            type: string
        subscription_status:
          type: string
        subscription_auto_attach:
          type: string
        katello_agent_running:
          type: boolean
        satellite_managed:
          type: boolean
        cloud_provider:
          type: string
        yum_repos:
          type: array  # technically a set, ordering is not important
          items:
            $ref: '#/components/schemas/YumRepo'
        installed_products:
          type: array  # technically a set, ordering is not important
          items:
            $ref: '#/components/schemas/InstalledProduct'
        insights_client_version:
          type: string
        insights_egg_version:
          type: string
        installed_packages:
          type: array  # technically a set, ordering is not important
          items:
            description: a NEVRA string for a single installed package
            type: string
            example:
              package:
                summary: package example
                value: "0:krb5-libs-1.16.1-23.fc29.i686"
        installed_services:
          type: array
          items:
            type: string
        enabled_services:
          type: array
          items:
            type: string
    PatchHostIn:
      title: Host data
      description: >-
        Data of a single host to be updated.
      type: object
      properties:
        ansible_host:
          description: >-
            The ansible host name for remediations
          type: string
          example: host1.mydomain.com
        display_name:
          description: >-
            A host’s human-readable display name, e.g. in a form of a domain
            name.
          type: string
          example: host1.mydomain.com