Chapter 2. API reference
The full API reference is available on your Satellite Server at https://satellite.example.com/apidoc/v2.html. 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 example requests below use python3 to format the respone from the Satellite Server. On RHEL 7 and some older systems, you must use python instead of python3.
The built-in API reference shows the API route, or path, preceded by an HTTP verb:
HTTP_VERB API_ROUTE
To work with the API, construct a command using the curl command syntax and the API route from the reference document:
$ curl --request HTTP_VERB \ 1 --insecure \ 2 --user sat_username:sat_password \ 3 --data @file.json \ 4 --header "Accept:application/json" \ 5 --header "Content-Type:application/json" \ 6 --output file 7 API_ROUTE \ 8 | python3 -m json.tool 9
- 1
- To use
curlfor the API call, specify an HTTP verb with the--requestoption. For example,--request POST. - 2
- Add the
--insecureoption to skip SSL peer certificate verification check. - 3
- Provide user credentials with the
--useroption. - 4
- For
POSTandPUTrequests, use the--dataoption to pass JSON formatted data. For more information, see Section 4.1.1, “Passing JSON data to the API request”. - 5 6
- When passing the JSON data with the
--dataoption, you must specify the following headers with the--headeroption. For more information, see Section 4.1.1, “Passing JSON data to the API request”. - 7
- When downloading content from Satellite Server, specify the output file with the
--outputoption. - 8
- Use the API route in the following format:
https://satellite.example.com/katello/api/activation_keys. In Satellite 6, version 2 of the API is the default. Therefore it is not necessary to usev2in the URL for API calls. - 9
- Redirect the output to the Python
json.toolmodule to make the output easier to read.
2.1.1. Using the GET HTTP verb
Use the GET HTTP verb to get data from the API about an existing entry or resource.
Example
This example requests the amount of Satellite hosts:
Example request:
$ curl --request GET --insecure --user sat_username:sat_password \ https://satellite.example.com/api/hosts | python3 -m json.tool
Example response:
{
"total": 2,
"subtotal": 2,
"page": 1,
"per_page": 20,
"search": null,
"sort": {
"by": null,
"order": null
},
"results":
output truncatedThe response from the API indicates that there are two results in total, this is the first page of the results, and the maximum results per page is set to 20. For more information, see Section 2.2, “Understanding the JSON response format”.
2.1.2. Using the POST HTTP verb
Use the POST HTTP verb to submit data to the API to create an entry or resource. You must submit the data in JSON format. For more information, see Section 4.1.1, “Passing JSON data to the API request”.
Example
This example creates an activation key.
Create a test file, for example,
activation-key.json, with the following content:{"organization_id":1, "name":"TestKey", "description":"Just for testing"}Create an activation key by applying the data in the
activation-key.jsonfile:Example request:
$ curl --header "Accept:application/json" \ --header "Content-Type:application/json" --request POST \ --user sat_username:sat_password --insecure \ --data @activation-key.json \ https://satellite.example.com/katello/api/activation_keys \ | python3 -m json.tool
Example response:
{ "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 } }- Verify that the new activation key is present. In the Satellite web UI, navigate to Content > Activation keys to view your activation keys.
2.1.3. Using the PUT HTTP verb
Use the PUT HTTP verb to change an existing value or append to an existing resource. You must submit the data in JSON format. For more information, see Section 4.1.1, “Passing JSON data to the API request”.
Example
This example updates the TestKey activation key created in the previous example.
Edit the
activation-key.jsonfile created previously as follows:{"organization_id":1, "name":"TestKey", "description":"Just for testing","max_hosts":"10" }Apply the changes in the JSON file:
Example request:
$ curl --header "Accept:application/json" \ --header "Content-Type:application/json" --request PUT \ --user sat_username:sat_password --insecure \ --data @activation-key.json \ https://satellite.example.com/katello/api/activation_keys/2 \ | python3 -m json.tool
Example response:
{ "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 } }- In the Satellite web UI, verify the changes by navigating to Content > Activation keys.
2.1.4. Using the DELETE HTTP verb
To delete a resource, use the DELETE verb with an API route that includes the ID of the resource you want to delete.
Example
This example deletes the TestKey activation key which ID is 2:
Example request:
$ curl --header "Accept:application/json" \ --header "Content-Type:application/json" --request DELETE \ --user sat_username:sat_password --insecure \ https://satellite.example.com/katello/api/activation_keys/2 \ | python3 -m json.tool
Example response:
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
2.1.5. 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]
2.2. Understanding the JSON response format
Calls to the API return results in JSON format. The API call returns the result for a single-option response or for responses collections.
The example requests below use python3 to format the respone from the Satellite Server. On RHEL 7 and some older systems, you must use python instead of python3.
JSON response format for single objects
You can use single-object JSON responses to work with a single object. API requests to a single object require the object’s unique identifier :id.
This is an example of the format for a single-object request for the Satellite domain which ID is 23:
Example request:
$ curl --request GET --insecure --user sat_username:sat_password \ https://satellite.example.com/api/domains/23 | python3 -m json.tool
Example response:
{
"id": 23,
"name": "qa.lab.example.com",
"fullname": "QA",
"dns_id": 10,
"created_at": "2013-08-13T09:02:31Z",
"updated_at": "2013-08-13T09:02:31Z"
}JSON response format for collections
Collections are a list of objects such as hosts and domains. The format for a collection JSON response consists of a metadata fields section and a results section.
This is an example of the format for a collection request for a list of Satellite domains:
Example request:
$ curl --request GET --insecure --user sat_username:sat_password \ https://satellite.example.com/api/domains | python3 -m json.tool
Example response:
{
"total": 3,
"subtotal": 3,
"page": 1,
"per_page": 20,
"search": null,
"sort": {
"by": null,
"order": null
},
"results": [
{
"id": 23,
"name": "qa.lab.example.com",
"fullname": "QA",
"dns_id": 10,
"created_at": "2013-08-13T09:02:31Z",
"updated_at": "2013-08-13T09:02:31Z"
},
{
"id": 25,
"name": "sat.lab.example.com",
"fullname": "SATLAB",
"dns_id": 8,
"created_at": "2013-08-13T08:32:48Z",
"updated_at": "2013-08-14T07:04:03Z"
},
{
"id": 32,
"name": "hr.lab.example.com",
"fullname": "HR",
"dns_id": 8,
"created_at": "2013-08-16T08:32:48Z",
"updated_at": "2013-08-16T07:04:03Z"
}
]
}The response metadata fields
API response uses the following metadata fields:
-
total— The total number of objects without any search parameters. -
subtotal— The number of objects returned with the given search parameters. If there is no search, then subtotal is equal to total. -
page— The page number. -
per_page— The maximum number of objects returned per page. -
limit— The specified number of objects to return in a collection response. -
offset— The number of objects skipped before returning a collection. -
search— The search string based onscoped_scopedsyntax. sort-
by— Specifies by what field the API sorts the collection. -
order— The sort order, either ASC for ascending or DESC for descending.
-
-
results— The collection of objects.
