System Comparison API Documentation
Using the REST API for the Insights for Red Hat Enterprise Linux drift service
Red Hat Customer Content Services
Abstract
Chapter 1. Using APIs for Queries
The drift service enables you to compare the system configuration of one system to that of other systems and baselines registered in your Insights for Red Hat Enterprise Linux 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.
- For additional Insights for Red Hat Enterprise Linux services for Red Hat Enterprise Linux API documentation, see https://cloud.redhat.com/docs/api-docs.
- For the latest OpenAPI Specification document, see OpenAPI Specification.
1.1. Schema
The API access is over HTTPS, and accessed from the root URL of https://access.redhat.com/documentation/en-us/red_hat_insights/2023/html/system_comparison_api_documentation/[System Comparison API Documentation. All data is sent and received as JSON. The JSON files include:
drift-openapi.json historical-system-profiles-openapi.json system-baseline-openapi.json
1.2. 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
1.3. Specification
1.3.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"
1.3.2. HTTP Methods
The HTTP methods currently supported for API requests are GET and POST.
1.3.3. Data Types
| Data Type | Description |
|---|---|
| Integer | Integer value |
| String | JSON string |
| Array |
The |
| Boolean | Value resulting in True or False |
| Timestamp | Timestamp in ISO8601 format |
1.3.4. HTTP Status Codes
| Code | Text | Description |
|---|---|---|
| 200 | OK | Success. |
| 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 2. Comparison Report API
The 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 simply need to fetch the information for a system and do not require comparison information, you can use the inventory API directly.
Currently, there is a 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. Such requests may hit the timeout limit set by the API infrastructure.
Example
The following example uses the comparison_report API to interact with registered systems in inventory to compare system configurations using the GET method. This request fetches the most current system state, using data from the inventory service for the given system IDs, and generates 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 forResponses:
'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'
Example
The following example uses the comparison_report API to interact with registered systems in inventory to compare system configurations by providing a JSON file as input using the POST method.
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
An example of JSON file content follows.
{"system_ids": ["UUID1", "UUID2", "UUID3"]}2.1. Systems Only Report Queries
You can query systems only reports using API:
GET api/drift/v1/comparison_report?system_ids[]=55e47a1d-05d7-4abb-963 a-ba513a0a57ad&system_ids[]=....
2.2. Systems and Baseline Report Queries
You can query systems and baseline reports using API:
GET api/drift/v1/comparison_report?system_ids[]=55e47a1d-05d7-4abb-963 a-ba513a0a57ad&baseline_ids[]=79032c7b-8284-44d0-b820-ebbb6d25c5e2
2.3. System and Historical System Profile Report Queries
You can query systems and historical system profile reports using API:
GET api/drift/v1/comparison_report?system_ids[]=55e47a1d-05d7-4abb-963 a-ba513a0a57ad&historical_system_profile_ids[]=5d7dd2e9-18e5-412e-8f25-efa8a96a4289
2.4. System, Baseline, and Historical System Profile Report Queries
You can query systems, baselines, and historical system profile reports using API:
GET api/drift/v1/comparison_report?system_ids[]=55e47a1d-05d7-4abb-963 a-ba513a0a57ad&baseline_ids[]=79032c7b-8284-44d0-b820-ebbb6d25c5e2 &historical_system_profile_ids[]=5d7dd2e9-18e5-412e-8f25-efa8a96a4 289
2.5. Exporting the Comparison Report API
You can use the comparison report API to export the entire comparison report output for the given systems, baselines, and historical system profile 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'
2.6. Reference Queries
You can set a reference in the query when using the API:
GET api/drift/v1/comparison_report?reference_id=UUID1&system_ids[]= 55e47a1d-05d7-4abb-963a-ba513a0a57ad&baseline_ids[]=79032c7b- 8284-44d0-b820-ebbb6d25c5e2&historical_system_profile_ids[]= 5d7dd2e9-18e5-412e-8f25-efa8a96a4289
The reference_id parameter is optional, and you can use only one reference ID in a query. You can set it to any used parameter in the comparison query: system ID, baseline ID, or historical system profile ID. When you use the reference ID, the Comparison service compares all systems, baselines, and historical system profiles in the list against it.
Chapter 3. Baselines API
Baselines are a set of facts that can be created and managed using the API.
The following command-line examples demonstrate how to use the baselines API to create and manage baselines. You can create baselines from scratch, or by copying from a system inventory ID, from a baseline ID, and from an historical system profile ID.
3.1. Creating a New Baseline From Scratch
You can create a new baseline from scratch.
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"
}The following examples show a CURL command using POST with the JSON data method for creating a new baseline from scratch.
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"
}
]
},
{:context: {parent-context}
"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"
}
3.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"
}3.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.
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’
- Select the baseline ID you want to copy from to create a new baseline.
Create a new baseline using the selected baseline ID via the POST method. 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
3.4. Copying a Historical System Profile to Create a New Baseline
You can copy a historical system profile to create a new baseline via API.
An example create-from-hsp.json file follows:
{"hsp_uuid": "<UUID>",
"display_name": "from-hsp1"}Request:
$ curl -k -X POST -d @create-from-hsp.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,
"HSP_uuid": "UUID",
"Updated": "2019-08-27T15:34:38.504298Z"
}3.5. Sorting Baselines
You can sort baselines via API using the GET method by appending order_by and order_how parameters.
-
order_byparameter accepts the following values:display_name,created_on, andupdated -
order_howparameter accepts the following values for sorting the results:ASC(ascending) andDESC(descending)
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
3.6. Editing a Baseline
You can edit a baseline via the API using the curl command.
$ curl -u username:password https://cloud.redhat.com/api/system-baseline/v1$/baselines/[uuid]
3.7. Exporting Baselines
You can export baselines as a CSV file via the API using the GET method.
$ curl -X GET https://username:password@cloud.redhat.com/api/system-baseline/v1/baselines -H ‘accept: text/csv’
3.8. Deleting a Baseline
You can delete a baseline using the API.
Use the following curl command to delete a baseline via the API.
$ curl -u username:password https://cloud.redhat.com/api/system-baseline/v1/baselines/[ID] -X DELETE
Chapter 4. Historical System Profiles API
Historical system profiles capture points in time for system profiles in Insights for Red Hat Enterprise Linux inventory. The profiles return lists of system profiles for a particular system.
The historical system profile has two main methods:
- Systems method
- Profiles method
4.1. Systems Method
The systems method returns a list of all historical system profiles for the system you specify in the uuid parameter.
Use the following curl command to get all historical system profiles for a system uuid.
$ curl -u username:password https://cloud.redhat.com/api/historical-system-profiles/v1/system/[ID]
For each profile, the service returns:
-
captured_date-- the date indicating when the system profile was captured -
an
id— which is the profileuuid. -
system_id-- the systemuuid, which is the same as what was specified in the request.
The following is a partial sample of the Systems method output you can expect to see:
{
"data": [
{
"profiles": [
{
"captured_date": "2020-10-28T06:23:25+00:00",
"id": "35054dcf-da10-489e-b383-8580511c8c10",
"system_id": "563f782e-6266-41f0-a761-0e0eab29463b"
},
{
"captured_date": "2020-10-27T18:43:28+00:00",
"id": "472ad292-e2b1-40ac-b514-502df11df765",
"system_id": "563f782e-6266-41f0-a761-0e0eab29463b"
},
{
"captured_date": "2020-10-27T06:14:13+00:00",
"id": "89235117-e9f5-4a2c-86d4-c3e908a392a7",
"system_id": "563f782e-6266-41f0-a761-0e0eab29463b"
},
{
"captured_date": "2020-10-26T07:34:17+00:00",
"id": "6652ba31-f5e5-45c6-ae59-8f8d51181358",
"system_id": "563f782e-6266-41f0-a761-0e0eab29463b"
},
{
"captured_date": "2020-10-25T06:40:18+00:00",
"id": "b66e8bb8-916c-409b-96d8-93119944e71d",
"system_id": "563f782e-6266-41f0-a761-0e0eab29463b"
},
{
"captured_date": "2020-10-24T06:23:19+00:00",
:context: {parent-context}
"id": "b7dadf95-90ec-4289-b50a-6c8d19124ccf",
"system_id": "563f782e-6266-41f0-a761-0e0eab29463b"
},
{
"captured_date": "2020-10-23T06:34:14+00:00",
"id": "3c9ce38d-22da-4d06-876d-35133eb5959e",
"system_id": "563f782e-6266-41f0-a761-0e0eab29463b"
},
{
"captured_date": "2020-10-22T05:59:09+00:00",
"id": "18cd803d-3f1f-4ce7-9bbf-6a6585dc9c03",
"system_id": "563f782e-6266-41f0-a761-0e0eab29463b"
}
]
}4.2. Profiles Method
The profiles endpoint returns system profile information for each profile ID you specify in the uuid parameter. The API takes one or more comma-separated historical system profile ids and returns system profile information for each id.
Use the following curl command to get historical system profiles passed as comma-separated parameters:
$ curl -u username:password https://cloud.redhat.com/api/historical-system-profiles/v1/profiles/[ID1],[ID2]
The following is a partial sample of the Profiles method output you can expect to see:
{
"data": [
{
"account": "ACCOUNTID",
"captured_date": "2020-10-27T18:43:28+00:00",
"created": "2020-10-27T18:43:48.340185+00:00",
"display_name": "dsmith-rhel82kvm",
"id": "472ad292-e2b1-40ac-b514-502df11df765",
"inventory_id": "563f782e-6266-41f0-a761-0e0eab29463b",
"system_profile": {
"arch": "x86_64",
"bios_release_date": "04/01/2014",
"bios_vendor": "SeaBIOS",
"bios_version": "1.12.0-2.fc30",
"captured_date": "2020-10-27T18:43:28+00:00",
"cores_per_socket": 2,
"cpu_flags": [ ],
:context: {parent-context} "display_name": "dsmith-rhel82kvm",
"dnf_modules": [ ],
"enabled_services": [ ],
"fqdn": "dsmith-rhel82kvm",
"id": "472ad292-e2b1-40ac-b514-502df11df765",
"infrastructure_type": "virtual",
"infrastructure_vendor": "kvm",
"insights_client_version": "3.0.12-0",
"insights_egg_version": "3.0.162-1",
"installed_packages": [ ],
"installed_products": [
"installed_services": [ ],
"kernel_modules": [ ],
"last_boot_time": "2020-05-01T02:11:28",
"network_interfaces": [ ],
"number_of_cpus": 8,
"number_of_sockets": 4,
"os_kernel_version": "4.18.0",
"os_release": "8.2",
"running_processes": [ ],
"satellite_managed": false,
"selinux_config_file": "enforcing",
"selinux_current_mode": "enforcing",
"system_memory_bytes": 1914204160,
"tags": [ ],
"tuned_profile": "virtual-guest",
"yum_repos": [ ]
}
}
]
}Providing feedback on Red Hat documentation
We appreciate your feedback on our documentation. To provide feedback, highlight text in a document and add comments.
Prerequisites
- You are logged in to the Red Hat Customer Portal.
- In the Red Hat Customer Portal, the document is in the Multi-page HTML viewing format.
Procedure
To provide your feedback, perform the following steps:
Click the Feedback button in the top-right corner of the document to see existing feedback.
NoteThe feedback feature is enabled only in the Multi-page HTML format.
- Highlight the section of the document where you want to provide feedback.
Click the Add Feedback pop-up that appears near the highlighted text.
A text box appears in the feedback section on the right side of the page.
Enter your feedback in the text box and click Submit.
A documentation issue is created.
- To view the issue, click the issue link in the feedback view.