Warning message

Log in to add comments.

Managing the Insights API

Amaya Gil published on 2019-01-30T12:20:50+00:00, last updated 2019-01-30T12:26:55+00:00

How to extend Insights capabilities by using the API

OK, APIs are cool, why? Because an API (acronym for Application Programming Interface), is a software intermediary that allows two applications to talk to each other, or in other words, a set of subroutine definitions, protocols, and tools for building application software. In short, an API is a way a vendor gives you to extend his product capabilities to your needs. So, yes, it IS cool.

But, is Insights also cool?

Pretty much, yes!

Other than the cool features (such as system configuration assessment and prescriptive remediate of issues before they become problems, tailored solutions to problems applicable only to your systems) Red Hat Insights already provides you with, it also allows you to extend its capabilities by using its RESTful API, with a programming language of your choice.

By default all Insights API resources are represented in application/json format. In addition, it is possible to export reports, inventory and maintenance plans as text/csv.

What is Red Hat Insights?

Haven't heard of Red Hat Insights yet? Well, it's time to fix that! Get familiar with Insights in this post today!

Get Started with Red Hat Insights API:

First of all, you need to choose a programming language to communicate with the API. I am using Python for its simplicity and popularity.

Important note:
These are example scripts and commands. Ensure you review these scripts carefully before use, and replace any variables, user names, passwords, and other information to suit your own deployment.

Accessing Red Hat Insights API in Python

The following script connects to the Red Hat Insights API and defines the variables to connect to your Red Hat Insights account:

import json
import sys

try:
    import requests
except ImportError:
    print("Please install the python-requests module.")
    sys.exit(-1)
 #URL to Insights
URL = "https://access.redhat.com/r/insights"
 #URL for the API to your deployed insights account
ACCOUNT_API = "%s/v1/account/" % URL
SYS_API = "%s/v1/groups" % URL
 #Default credentials to login to your Insights Account, please change
USERNAME = "changeme"
PASSWORD = "changeme"
SSL_VERIFY = True
POST_HEADERS = {'content-type': 'application/json'}

Please note, that in order to work, this script requires the requests and json modules to be installed separately in your Python environment.

Now it is time to get our hands dirty by calling the API to retrieve some information from our account.

Retrieving data using the API and Python

In this example I am using API v1, as this is the version you will find on the official documentation site however, we are currently on v3. Most of the resources did not change between v1 and v3, and in the particular case of this example, it will run fine in all of the versions.

So, first we need to authenticate with Red Hat Insights, I will use HTTPS and my account credentials, for that I need to connect to the API using SYS_API variable and the type of query we are going to do (variable payload), as the API tells us to.

Note: I am getting systems information from “/groups” which is odd, but the idea behind it is to be able to get the information about systems by its groups, as an example just for learning purposes. If you just want to get system information, you’d better use “/system” (from the API)

Groups

I only need to call the API with the URL I want to query (SYS_API variable in this case) and include systems (payload variable).

After I retrieve all the information relative to systems on my account (in JSON format) I call a function to print it in a nice way.

def main():
    """
    Main routine that creates or re-uses an organization and
    life cycle environments. If life cycle environments already
    exist, exit out.
    """

    payload = {'include': 'systems'}
    insights_request = InsightsRequest(SYS_API, payload)
    cute_output(insights_request)

To print the JSON data, I store it on an Python list object (json_report) and then, simply walk through it, displaying the info in different lines and tabulated, so it is easier to read.

Fields to be printed are a personal choice, since the object has many more than the ones in this example, in fact, it has all the information related to systems (architecture, OS version, account number, updated date, and a very long etcetera).

def cute_output(insights_request):
    """
    Prints desired values of the object in a nicer form
    :param insights_request:
    :return:
    """
    json_report = insights_request.get_insights()

    if not json_report:
        print('Error ocurred, unable to print!!!')
    else:
        for groups in json_report:
            print('GROUP: ' + groups['display_name'])
            for systems in groups['systems']:
                print('\n\t\t Host name: ' + systems['hostname'])
                print('\n\t\t Product: ' + systems['product'])
                print('\n\t\t Type: ' + systems['type'])
                print('\n\t\t Registered at Insights: ' + systems['created_at'])
                print('\n\t\t Last checked at Insights: ' + systems['last_check_in'] + '\n\n')

To retrieve data, initialize the class with a default URL (as the API has to be always queried using an URL that changes with the different options to be queried) and then when the query is done by calling get_insights() method, I simply pass the credentials, method (HTTP or HTTPS) and additional data, when needed.

Finally, I review the HTTP response, and if it’s ok, I return the JSON object, so I can print it with the method above.

class InsightsRequest:

    def __init__(self, location, data=None):
        """
        Class constructor
        :param location:
        :param data:
        """
        self.location = location
        self.data = data

    def get_insights(self):
        """
        Performs a GET using the passed URL location
        """
        r = requests.get(
            self.location,
            auth=(USERNAME, PASSWORD),
            verify=SSL_VERIFY,
            params=self.data)

        if self._check_http_response(r):
            return r.json()
        else:
            return None

As you can see, querying Red Hat Insights API is quite easy using (in this case) Python and also very flexible; it allows you to extend the capabilities of the product to adapt it to your specific needs.

This is a basic example of how to query and retrieve information using the Insights API, but you can also create and delete objects using your Red Hat Insights account by using the API.

NOTE: I want to thank Roberto Bergantiños (Software Maintenance Engineer at Red Hat) for co-authoring this post.

English

About The Author

Amaya Gil's picture Red Hat Community Member 56 points

Amaya Gil

Born and raised in Madrid (Spain) of Spanish, Italian and Argentinian roots. Computer Science Engineer (BS and MS), technology passionate, Red Hatter since 2.010. Proud RHCA, Technical Marketing Manager in the Management BU at Red Hat.