System Comparison API Documentation

Red Hat Insights 2020-04

Using the System Comparison REST API

Red Hat Customer Content Services

Abstract

This document provides web services available to integrate System Comparison with external applications. It describes the specification of the System Comparison RESTful API, which is implemented as standard REST HTTP requests and responses of content type JSON.
Providing Feedback:
If you have a suggestion to improve this document or find an error, submit a Bugzilla report at http://bugzilla.redhat.com against Cloud Software Services (cloud.redhat.com) for the System Comparison component.

Chapter 1. Overview

System Comparison enables you to compare system configuration of one system to other systems and baselines registered in your cloud management services inventory. It allows you to query system configurations using a REST API, create and manage baselines, and returns fact values as well as comparison states. You can also generate CSV output of the systems and baselines you are comparing.

Note

Chapter 2. Schema

The API access is over HTTPS, and accessed from the root URL of https://cloud.redhat.com/api/drift. All data is sent and received as JSON.

Chapter 3. Basic Authentication

The user and password credentials are passed in with each HTTP request.

Request

$ curl --user username:password -i https://cloud.redhat.com/api/drift/v1/comparison_report?system_ids[]=<UUID>

or

$ curl --user username:password -i https://cloud.redhat.com/api/system-baseline/v1/baselines

Chapter 4. Specification

4.1. REST API Entry Point

The REST API is available via the /api URL prefix. It is accessed on the server as follows:

"/api/drift/v1"

4.2. Methods

The HTTP methods currently supported for API requests are GET and POST.

4.3. Data Types

Data TypeDescription

Integer

Integer value

String

JSON string

Array

The items keyword is required in arrays. The value of items is a schema that describes the type and format of array items. Arrays can be nested.

Boolean

Value resulting in True or False

Timestamp

Timestamp in ISO8601 format

4.4. HTTP Status Code

CodeTextDescription

200

OK

Success. A comparison report for the given system IDs.

400

Bad Request

The request could not be understood by the server due to incorrect syntax.

500

Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request.

Chapter 5. Comparison_Report API

The main purpose of the comparison report is to fetch system profiles for the systems requested, pull their facts from the inventory service, and then transform those facts into a comparison report. If you are simply trying to fetch the information for a system and do not require comparison information, you can use the inventory API directly.

Note

There is currently 45 system limit when comparing systems via either the web user interface or API. Requests to compare more than 45 systems at a time may result in a 400 error. Also, requests may also hit the timeout limit set by the API infrastructure.

Example using the GET method:

The following is an example of using the comparison_report API to interact with registered systems in inventory to compare system configurations using the GET method. This will fetch the most current system state using data from inventory service for given system IDs and generate a comparison report.

Request:

GET /api/drift/v1/comparison_report?system_ids=<UUID>&system_ids=<UUID>

openapi: 3.0.1
info:
  version: "1.0"
  title: Drift Backend Service
  description: Service that returns differences between systems.
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html

servers:
  - url: "/api/drift/v1"

paths:
  /comparison_report:
    parameters:
      - $ref: '#/components/parameters/rhIdentityHeader'
    get:
      summary: fetch comparison report
      description: "Fetch a comparison report for given system IDs. This will only fetch the most current system state using data from inventory service."
      operationId: drift.views.v1.comparison_report
      parameters:
        - name: system_ids[]
          in: query
          schema:
            type: array
            items:
              type: string
              format: uuid
          required: true
          description: list of system IDs to generate report for

Responses:

        '200':
          description: a comparison report for the given system IDs
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComparisonReport"
              examples:
                jsonObject:
                  summary: A sample comparison report
                  externalValue: "https://git.io/fhQ00"
        '400':
         	$ref: '#/components/responses/BadRequest'
        '500':
		$ref: '#/components/responses/InternalServerError'

Command-line example with curl using the POST method:

The following is an example of using the comparison_report API to interact with registered systems in inventory to compare system configurations by providing JSON file as input using the POST method.

Note

There is no system limit when comparing systems using the POST method via API.

Request:

$ curl -k -u username:password -X POST --header "Content-Type: application/json" https://cloud.redhat.com/api/drift/v1/comparison_report -d @/directory/example-uuid-file.json

Example .json file content:

{"system_ids": ["UUID1", "UUID2", "UUID3"]}

5.1. Exporting Comparison_Report API

You can use the comparison_report API to export the entire comparison report output for the given systems and baselines IDs without any filters. The output includes all facts including categories (parent facts) and sub facts, and their values in a comma-separated values (CSV) format.

Request:

$ curl -X GET ‘https://username:password@cloud.redhat.com/api/drift/v1/comparison_report?baseline_ids[]=UUID1&system_ids[]=UUID2&system_ids[]=UUID3’ -H ‘accept: text/csv’

Chapter 6. Baselines API

Baselines are set of facts that can be created and managed using the API. You can compare system configurations to one or more baselines to identify discrepancies in your environment, export the output in CSV format, and perform drift analysis.

The following command-line examples demonstrate how to use the baselines API to interact with registered systems in the inventory to create and manage baselines by providing JSON file as input.

6.1. Creating a New Baseline

An example of a create.json file follows:

{
    	"baseline_facts": [
	    {
	    "name": "fact name 1",
	    "value":  "fact value 1"
	    },
	    {
	    "name": "fact name 2",
	    "value":  "fact value 2"
	    },
            {
            "name": "category 1",
            "values": [
               {
               "name": "sub fact name 1",
               "value":  "sub fact value 1"
               }
      ]
      }
],
"display_name": "demo baseline"
}

Request:

$ curl -u username:password
https://cloud.redhat.com/api/system-baseline/v1/baselines -X
POST -d @create.json -H "content-type: application/json"

Response:

{
  "account": "[account number]",
  "baseline_facts": [
    {
      "name": "category 1",
      "values": [
           {
             "name": "sub fact name 1",
             "value": " sub fact value 1"
            }
            ]
            },
      {
        "name": "fact name 1",
        "value": "fact value 1"
       },
       {
        "name": "fact name 2"
        "value": "fact value 2"
       }
    ],
  "created": "2020-05-18T20:25:36.328741Z",
  "display_name": "demo baseline",
  "fact_count": 3,
  "id": "9565f205-5816-43b4-953e-a29fed8b40ec",
  "updated": "2020-05-18T20:25:36.328745Z"
}

6.2. Copying an Existing System to Create a New Baseline

You can copy an existing system to create a new baseline via API.

An example create-from-inv.json file follows:

{"inventory_uuid": "<UUID>",
"display_name": "from-inv1"}

Request:

$ curl -k -X POST  -d @create-from-inv.json
https://username:password@cloud.redhat.com/api/system-baseline/v1/baselines
-H ‘content-type: application/json’

Response:

Note that some of the facts have been removed from the response to improve readability.

{
[
{
	"Name": "number_of_sockets",
	"Value": "1"
},
{
	"Name": "cores_per_socket",
	"Value": "1"
},
{
	"Name": "number_of_cpus",
	"Value": "None"
},
{
	"Name": "system_memory",
        "Value":  "488.35 MiB"
}
],
"Created": "2019-08-27T15:34:38.504298Z",
"Display_name": "from-inv1",
"Fact_count": 20,
"Id": "UUID",
"Updated": "2019-08-27T15:34:38.504298Z"
}

6.3. Copying an Existing Baseline to Create a New Baseline

You can copy an existing baseline to create a new baseline via API using the GET and POST methods.

  1. First, obtain the list of existing baseline IDs via GET:

    $ curl -X GET  https://username:password@cloud.redhat.com/api/system-baseline/v1/baselines -H ‘content-type: application/json’
  2. Select the baseline ID you want to copy from to create a new baseline.
  3. Create a new baseline using the selected baseline ID via POST. You must provide a new display name, otherwise it will result in a 400 error.

    $ curl -X POST  https://username:password@cloud.redhat.com/api/system-baseline/v1/baselines/<ID>?display_name=copied-from-baseline-name

6.4. Sorting Baselines

You can sort baselines via API using the GET method by appending order_by and order_how parameters.

  • order_by parameter accepts the following values: display_name, created_on
  • order_how parameter accepts the following values for sorting the results: ASC (ascending) and DESC (descending)

Note that by default results are sorted by alphabetical order on display name.

Request:

$ curl -X GET  https://username:password@cloud.redhat.com/api/system-baseline/v1/baselines?order_by=created_on&order_how=DESC

6.5. Exporting Baselines

You can export baselines via API using the GET method.

$ curl -X GET https://username:password@cloud.redhat.com/api/system-baseline/v1/baselines -H ‘accept: text/csv’

6.6. Deleting a Baseline

Use the following curl command to delete a baseline via API.

$ curl -u username:password https://cloud.redhat.com/api/system-baseline/v1/baselines/[ID] -X DELETE

Legal Notice

Copyright © 2020 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.