Chapter 2. API Reference

The full API reference is available on your Satellite Server at https://satellite6.example.com/apidoc/v2.html (replace satellite6.example.com with the host name of your Satellite Server). Be aware that even though versions 1 and 2 of the Satellite 6 API are available, Red Hat only supports version 2.

2.1. Understanding the API Syntax

The built-in API reference shows the API route, or path, preceded by an HTTP verb:
HTTP_VERB API_ROUTE
The HTTP verbs used by the API are GET, POST, PUT, and DELETE. See the HOSTS section of the API reference document at http://satellite6.example.com/apidoc/v2/hosts.html for some examples. If you are already familiar with API syntax and the curl command you can skip this section.
To work with the API, construct a command using the API route from the reference document and the command syntax from the documentation for the command. For example, the curl manual page show the following basic syntax:
curl [options] [URL...]
The options used in this guide include: -X, --request command, where command is an HTTP verb.

Using the GET HTTP Verb

The GET HTTP verb is used to get data from the API about an existing entry or resource.
Combining an example from the API HOSTS section such as GET /api/hosts with the curl syntax results in:
curl -X GET https://satellite6.example.com/api/hosts
Satellite only supports HTTPS for connecting to the API, and some form of authentication is required.
For a usable example, we must add at least a user name with the -u option, and the -k option to skip SSL peer certificate verification checks:
$ curl -X GET -k -u sat_username https://satellite6.example.com/api/hosts
Enter host password for user 'sat_username':
{
  "total": 2,
  "subtotal": 2,
  "page": 1,
  "per_page": 20,
  "search": null,
  "sort": {
    "by": null,
    "order": null
  },
  "results":
	output truncated
The above response from the API indicates that there are two results in total, two results are being returned below, this is the first page of the results, and the maximum results per page is set to 20. This is explained more verbosely in Section 2.2, “Understanding the JSON Response Format”.
Some examples in the API reference include terms preceded by a colon in the form :parameter. For example:
GET /api/hosts/:id
These are API route parameters and must be replaced by an appropriate value. Route parameters start with a colon and end with id.

Note

In Satellite 6, version 2 of the API is the default. Therefore it is not necessary to use v2 in the URL for API calls.

Using the POST HTTP Verb

The POST HTTP verb is used to submit data to the API to create a new entry or resource. The data must be in JSON format, and can be included inline using the -d, --data option followed by the quoted JSON formatted data enclosed in braces {}. Alternatively, the unquoted JSON formatted data can be enclosed in a file, and specified using the curl command's @ option. For example, -d @file.json.
The advantages of using external files for JSON formatted data include less problems with quoting and escaping, being able to use your favorite editor with syntax checkers to help you find and avoid mistakes, and external tools to check the validity of JSON data or to reformat it. For example, the yajl package contains the json_verify tool and the json_reformat tool.
Using the json_verify tool, you can check the validity of a JSON file as follows:
$ json_verify < test_file.json
The unstructured JSON data returned by an API call can be piped through the python module json.tool:
curl API_call | python -m json.tool
Alternately, use the json_reformat tool:
curl API_call | json_reformat
The output format is explained in Section 2.2, “Understanding the JSON Response Format”.
The API Reference includes the following in the Activation keys section:
POST /katello/api/activation_keys
This is one possible format for a POST /katello/api/activation_keys command:
curl -X POST -k -u sat_username:sat_password \
-d @file_of_json-formatted_data \
https://satellite6.example.com/katello/api/activation_keys
To see how the POST HTTP verb works, create a test file, for example, activation-key.json, with contents as follows:
{"organization_id":1, "name":"TestKey", "description":"Just for testing"}
The following example will create a new Activation key by applying the data in the file just created:
$ curl -H "Accept:application/json,version=2" \
-H "Content-Type:application/json" -X POST \
-u sat_username:sat_password -k \
-d @activation-key.json \
https://satellite6.example.com/katello/api/activation_keys | json_reformat
{
    "id": 2,
    "name": "TestKey",
    "description": "Just for testing",
    "unlimited_hosts": true,
    "auto_attach": true,
    "content_view_id": null,
    "environment_id": null,
    "usage_count": 0,
    "user_id": 3,
    "max_hosts": null,
    "release_version": null,
    "service_level": null,
    "content_overrides": [

    ],
    "organization": {
        "name": "Default Organization",
        "label": "Default_Organization",
        "id": 1
    },
    "created_at": "2017-02-16 12:37:47 UTC",
    "updated_at": "2017-02-16 12:37:48 UTC",
    "content_view": null,
    "environment": null,
    "products": null,
    "host_collections": [

    ],
    "permissions": {
        "view_activation_keys": true,
        "edit_activation_keys": true,
        "destroy_activation_keys": true
    }
}
To view this entry in the web UI, navigate to ContentActivation keys. Remember to reload the page after any changes.

Using the PUT HTTP Verb

The PUT HTTP verb is used to submit data to the API to update an existing entry or resource. Similarly to the POST API call, the data must be in JSON format, and can be included inline using the -d, --data option followed by the quoted JSON formatted data enclosed in braces {}. Alternatively, the unquoted JSON formatted data can be enclosed in a file, and specified using the curl command's @ option. For example, -d @file.json.
To change an existing value or append to an existing resource use the PUT HTTP verb. The API reference has the following entry for updating an Activation key:
PUT /katello/api/activation_keys/:id
To update an existing Activation key, use a command in the following format:
curl -X PUT -k -u sat_username:sat_password \
-d @file_of_json-formatted_data \
https://satellite6.example.com/katello/api/activation_keys/:id
Replace :id with the ID of the Activation key to be updated. Using the PUT command multiple times with the same values will not create multiple entries.
For example, the test Activation key created in the previous example can be updated by editing the file created previously as follows:
{"organization_id":1, "name":"TestKey", "description":"Just for testing","max_hosts":"10" }
Use a command as follows to apply the changes in the JSON file:
$ curl -H "Accept:application/json,version=2" \
-H "Content-Type:application/json" -X PUT \
-u sat_username:sat_password -k \
-d @activation-key.json \
https://satellite6.example.com/katello/api/activation_keys/2
{
    "id": 2,
    "name": "TestKey",
    "description": "Just for testing",
    "unlimited_hosts": false,
    "auto_attach": true,
    "content_view_id": null,
    "environment_id": null,
    "usage_count": 0,
    "user_id": 3,
"max_hosts": 10,
    "release_version": null,
    "service_level": null,
    "content_overrides": [

    ],
    "organization": {
        "name": "Default Organization",
        "label": "Default_Organization",
        "id": 1
    },
    "created_at": "2017-02-16 12:37:47 UTC",
    "updated_at": "2017-02-16 12:46:17 UTC",
    "content_view": null,
    "environment": null,
    "products": null,
    "host_collections": [

    ],
    "permissions": {
        "view_activation_keys": true,
        "edit_activation_keys": true,
        "destroy_activation_keys": true
    }
}

Using the DELETE HTTP Verb

To delete a resource, use the DELETE verb with an API route that includes the ID of the resource to be deleted.
To delete an existing Activation key, use a command in the following format:
curl -X DELETE -k -u sat_username:sat_password \
https://satellite6.example.com/katello/api/activation_keys/:id
Replace :id with the ID of the Activation key to be deleted. For example:
$ curl -H "Accept:application/json,version=2" \
-H "Content-Type:application/json" -X DELETE \
-u admin:RedHat1! -k \
https://satellite6.example.com/katello/api/activation_keys/2 | json_reformat
output omitted
    "started_at": "2017-02-16 12:58:17 UTC",
    "ended_at": "2017-02-16 12:58:18 UTC",
    "state": "stopped",
    "result": "success",
    "progress": 1.0,
    "input": {
        "activation_key": {
            "id": 2,
            "name": "TestKey"
output truncated

Relating API Error Messages to the API Reference

The API uses a RAILs format to indicate an error:
Nested_Resource.Attribute_Name
This translates to the following format used in the API reference:
Resource[Nested_Resource_attributes][Attribute_Name_id]