Chapter 3. API syntax You can review the basic syntax of API requests and JSON responses. Important Even though versions 1 and 2 of the Satellite 6 API are available, Red Hat only supports version 2. 3.1. API request composition The built-in API reference shows the API route, or path, preceded by an HTTP method: To work with the API, construct a command by using the curl command syntax and the API route from the reference document: 1 To use curl for the API call, specify an HTTP method with the --request option. For example, --request POST . 2 Add the --insecure option to skip SSL peer certificate verification check. Red Hat recommends you to configure SSL authentication and use secured calls. For more information, see Section 4.1, "SSL authentication overview" . 3 Provide Satellite user credentials with the --user option. 4 For POST and PUT requests, use the --data option to pass JSON-formatted data. For more information, see Section 5.1.1, "Passing JSON data to the API request" . 5 6 When passing the JSON data with the --data option, you must specify the following headers with the --header option. For more information, see Section 5.1.1, "Passing JSON data to the API request" . 7 When downloading content from Satellite Server, specify the output file with the --output option. 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 use v2 in the URL for API calls. 9 Redirect the output to the Python json.tool module to make the output easier to read. 3.1.1. Using the GET HTTP method Use the GET HTTP method to get data from the API about an existing entry or resource. Example This example requests the amount of Satellite hosts: Example request: Example response: The 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 3.2, "JSON response format" . 3.1.2. Using the POST HTTP method 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 5.1.1, "Passing JSON data to the API request" . Example to create an activation key Create a test file, for example, activation-key.json , with the following content: Create an activation key by applying the data in the activation-key.json file: Example request: Example response: Verify that the new activation key is present. In the Satellite web UI, navigate to Content > Lifecycle > Activation Keys to view your activation keys. 3.1.3. Using the PUT HTTP method Use the PUT HTTP method to change an existing value or append to an existing resource. You must submit the data in JSON format. For more information, see Section 5.1.1, "Passing JSON data to the API request" . Example This example updates the TestKey activation key created in the example. Edit the activation-key.json file created previously as follows: Apply the changes in the JSON file: Example request: Example response: In the Satellite web UI, verify the changes by navigating to Content > Lifecycle > Activation Keys . 3.1.4. Using the DELETE HTTP method To delete a resource, use the DELETE method 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: Example response: 3.2. 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. 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 unique identifier :id of the object. This is an example of the format for a single-object request for the Satellite domain which ID is 23: Example request: Example response: 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: Example response: JSON response metadata 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 on scoped_scoped syntax. 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. 3.3. Relating API error messages to the API reference The API uses a RAILs format to indicate an error: This translates to the following format used in the API reference:

Commands:
HTTP_METHOD API_ROUTE
curl --request HTTP_METHOD \ 1 --insecure \ 2 --user My_User_Name : My_Password \ 3 --data @ input_file .json \ 4 --header "Accept:application/json" \ 5 --header "Content-Type:application/json" \ 6 --output output_file 7 API_ROUTE \ 8 | python3 -m json.tool 9
curl --request GET --user My_User_Name : My_Password https:// satellite.example.com /api/hosts | python3 -m json.tool
{ "total": 2, "subtotal": 2, "page": 1, "per_page": 20, "search": null, "sort": { "by": null, "order": null }, "results": output truncated
organization_id: 1
name: TestKey
description: Just for testing
curl --header "Accept:application/json" --header "Content-Type:application/json" --request POST --user My_User_Name : My_Password --data @activation-key.json https:// satellite.example.com /katello/api/activation_keys | python3 -m json.tool
{ "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 } }
organization_id: 1
name: TestKey
description: Just for testing
max_hosts: 10
curl --request PUT --header "Accept:application/json" --header "Content-Type:application/json" --user My_User_Name : My_Password --data @activation-key.json https:// satellite.example.com /katello/api/activation_keys/2 | python3 -m json.tool
{ "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 } }
curl --header "Accept:application/json" --header "Content-Type:application/json" --request DELETE --user My_User_Name : My_Password https:// satellite.example.com /katello/api/activation_keys/2 | python3 -m json.tool
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
curl --request GET --user My_User_Name : My_Password https:// satellite.example.com /api/domains/23 | python3 -m json.tool
id: 23
name: qa.lab.example.com
fullname: QA
dns_id: 10
created_at: 2024-08-13T09:02:31Z
updated_at: 2024-08-13T09:02:31Z
curl --request GET --user My_User_Name : My_Password https:// satellite.example.com /api/domains | python3 -m json.tool
{ "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": "2024-08-13T09:02:31Z", "updated_at": "2024-08-13T09:02:31Z" }, { "id": 25, "name": "dev.lab.example.com", "fullname": "DEVEL", "dns_id": 8, "created_at": "2024-08-13T08:32:48Z", "updated_at": "2024-08-14T07:04:03Z" }, { "id": 32, "name": "hr.lab.example.com", "fullname": "HR", "dns_id": 8, "created_at": "2024-08-16T08:32:48Z", "updated_at": "2024-08-16T07:04:03Z" } ] }
Nested_Resource . Attribute_Name
Resource [ Nested_Resource_attributes ][ Attribute_Name_id ]