Chapter 2. API Reference

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.

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.

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 Content → Activation keys. Remember to reload the page after any changes.

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
    }
}

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

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]