Use REST API in Red Hat Update Infrastructure

Red Hat Update Infrastructure has a REST (Representational State Transfer) API (Application Programming Interface). The REST API is disabled by default.

Before you begin

  • Make sure that you have reviewed the Red Hat Update Infrastructure 5 Installation and Management guide.
  • You must be authenticated to the Red Hat Container Registry (registry.redhat.io) to pull the required images. Important

    Before you can use the API to add repositories or check for unused products, the entitlement mappings cache must be created, which further depends on the existence of the Red Hat Update Infrastructure entitlement certificate in the RHUA container. If you have SSH access to the RHUA, you can speed this up by following the instructions in Managing Repositories. Otherwise, wait until the relevant systemd timers run, which can take up to 7 hours in total. The API responds with the following error until the cache has been created:

    {"op": "repo_add", "type": "error", "error": "internal_error", "message": "The entitlement mappings cache doesn't exist."}

    Note that the cookie is only valid for 120 seconds by default. Be sure to refresh it regularly, or set a longer session length.

Procedure

  1. Access the REST API at https://<RHUA HOSTNAME>/rhui/api/v1/<PATH>[?<QUERY PARAMETERS>]. Make sure port 443 on the RHUA host is accessible from the system that should have access to the API. To communicate with the RHUA securely, make sure your client uses the CA certificate that is configured for the RHUA web server, which is saved in /var/lib/rhui/pki/certs/ca.crt on the RHUA host (or in general, in the file inside the RHUA container which is configured in the rhui_ca_crtoption` in the [security] section in /etc/rhui-static/rhui-tools-static.conf or overridden in /etc/rhui/rhui-tools.conf).
  2. To use the REST API, you must supply either the Red Hat Update Infrastructure administrator credentials (as HTTP Basic authentication) or a valid cookie. You may, however, use the credentials as data for the /login API call (see below) to obtain a cookie and then use the cookie in subsequent API calls (until the cookie expires).
    Note

    The application/json Content Type is required for all POST requests.
  3. The following is an example of an API call with the curl command that uses the credentials to obtain a cookie and save it to a local file: 
    $ curl --cacert ca.crt -c cookie.jar -H 'Content-Type: application/json' -d '{"username": "admin", "password": "<PASSWORD>"}' https://<RHUA HOSTNAME>/rhui/api/v1/login

    The following is an example of an API call using the cookie obtained in the previous step:

    $ curl --cacert ca.crt -b cookie.jar https://<RHUA HOSTNAME>/rhui/api/v1/repo/list

    The following is an example of an API call using HTTP Basic authentication:

    $ curl -v --cacert ca.crt -u admin https://<RHUA HOST>/rhui/api/v1/tasks/running
    Note

    In this case, curl prompts for the password.

    The available API calls are described below. In addition, if <RHUA HOSTNAME>:443 is accessible from your workstation, you can view an enriched version of the API documentation at https://<RHUA HOSTNAME>/rhui/api/docs/.