Chapter 6. API cheat sheet

1. Create an upload request.
2. Upload the content.
3. Import the content.
4. Delete the upload request.

Procedure

1. Assign the package name to the variable name:

   Example request:

   $ export name=jq-1.6-2.el7.x86_64.rpm

2. Assign the checksum of the file to the variable checksum:

   Example request:

   $ export checksum=$(sha256sum $name|cut -c 1-65)

3. Assign the file size to the variable size:

   Example request:

   $ export size=$(du -bs $name|cut -f 1)

4. Create an upload request that returns the upload ID of the request by using size and checksum.

   Example request:

   $ curl \
   --header 'Content-Type: application/json' \
   --request POST \
   --user My_User_Name:My_Password \
   --data "{\"size\": \"$size\", \"checksum\":\"$checksum\"}" \
   https://satellite.example.com/katello/api/v2/repositories/76/content_uploads

   where 76, in this case, is an example Repository ID.

   Example request:

   {"upload_id":"37eb5900-597e-4ac3-9bc5-2250c302fdc4"}

5. Assign the upload ID to the variable upload_id:

   $ export upload_id=37eb5900-597e-4ac3-9bc5-2250c302fdc4

6. Assign the path of the package you want to upload to the variable path:

   $ export path=/root/jq/jq-1.6-2.el7.x86_64.rpm

7. Upload your content. Ensure you use the correct MIME type when you upload data. The API uses the application/json MIME type for the requests to Satellite unless stated otherwise. Combine the upload ID, MIME type, and other parameters to upload content.

   Example request:

   $ curl \
   --user My_User_Name:My_Password \
   --header Accept:application/json \
   --header Content-Type:multipart/form-data \
   --request PUT \
   --data-urlencode size=$size \
   --data-urlencode offset=0 \
   --data-urlencode content@${path} \
   https://satellite.example.com/katello/api/v2/repositories/76/content_uploads/$upload_id

8. After you have uploaded the content to your Satellite Server, you need to import it into the appropriate repository. Until you complete this step, Satellite Server does not detect the new content.

   Example request:

   $ curl \
   --header "Content-Type:application/json" \
   --request PUT \
   --user My_User_Name:My_Password \
   --data "{\"uploads\":[{\"id\": \"$upload_id\", \"name\": \"$name\", \"checksum\": \"$checksum\" }]}" \
   https://satellite.example.com/katello/api/v2/repositories/76/import_uploads

9. After you have successfully uploaded and imported your content, you can delete the upload request. This frees any temporary disk space that data is using during the upload.

   Example request:

   $ curl \
   --header 'Content-Type: application/json' \
   --request DELETE \
   --user My_User_Name:My_Password \
   --data "{}" \
   https://satellite.example.com/katello/api/v2/repositories/76/content_uploads/$upload_id

Procedure

1. In the Satellite web UI, navigate to Hosts > All Hosts.
2. Click the Search field to display a list of search parameters.
3. Locate the search parameters that you want to use. For this example, locate os_title and model.

4. Combine the search parameters in your API query as follows:

   Example request:

   $ curl \
   --user My_User_Name:My_Password \
   https://satellite.example.com/api/v2/hosts?search=os_title=\"RedHat+7.7\",model=\"PowerEdge+R330\" \
   | python3 -m json.tool

   Example response:

     {
       ...
       "results": [
           {
               "model_id": 1,
               "model_name": "PowerEdge R330",
               "name": "satellite.example.com",
               "operatingsystem_id": 1,
               "operatingsystem_name": "RedHat 7.7",
               ...
           }
       ],
       "search": "os_title=\"RedHat 7.7\",model=\"PowerEdge R330\"",
       "subtotal": 1,
       "total": 11
   }

Procedure

1. Find the ID of the Smart Class parameter you want to change:

   • List all Smart Class Parameters.

     Example request:

     $ curl \
     --request GET \
     --user My_User_Name:My_Password \
     https://satellite.example.com/api/smart_class_parameters

   • If you know the Puppet class ID, for example 5, you can restrict the scope: Example request:

     $ curl \
     --request GET \
     --user My_User_Name:My_Password \
     https://satellite.example.com/api/puppetclasses/5/smart_class_parameters

     Both calls accept a search parameter. You can view the full list of searchable fields in the Satellite web UI. Navigate to Configure > Smart variables and click in the search query box to reveal the list of fields.

     Two particularly useful search parameters are puppetclass_name and key, which you can use to search for a specific parameter. For example, use the --data option to pass URL encoded data.

     Example request:

     $ curl \
     --request GET \
     --user My_User_Name:My_Password \
     --data 'search=puppetclass_name = access_insights_client and key = authmethod' \
     https://satellite.example.com/api/smart_class_parameters

     Satellite supports standard scoped-search syntax.

2. When you find the ID of the parameter, list the full details including current override values.

   Example request:

   $ curl \
   --request GET \
   --user My_User_Name:My_Password \
   https://satellite.example.com/api/smart_class_parameters/63

3. Enable overriding of parameter values.

   Example request:

   $ curl \
   --header "Accept:application/json" \
   --header "Content-Type:application/json" \
   --request PUT \
   --user My_User_Name:My_Password \
   --data '{"smart_class_parameter":{"override":true}}' \
   https://satellite.example.com/api/smart_class_parameters/63

   Note that you cannot create or delete the parameters manually. You can only modify their attributes. Satellite creates and deletes parameters only upon class import from Capsules.

4. Add custom override matchers.

   Example request:

   $ curl \
   --header "Accept:application/json" \
   --header "Content-Type:application/json" \
   --request PUT \
   --user My_User_Name:My_Password \
   --data '{"smart_class_parameter":{"override_value":{"match":"hostgroup=Test","value":"2.4.6"}}}' \
   https://satellite.example.com/api/smart_class_parameters/63

   For more information about override values, see https://satellite.example.com/apidoc/v2/override_values.html.

5. You can delete override values.

   Example request:

   $ curl \
   --request DELETE \
   --user My_User_Name:My_Password \
   https://satellite.example.com/api/smart_class_parameters/63/override_values/3

API procedure

1. Search for the Puppet Class by name, motd in this case.

   Example request:

   $ curl \
   --header "Accept:application/json" \
   --header "Content-Type:application/json" \
   --request GET \
   --user My_User_Name:My_Password \
   https://satellite.example.com/api/smart_class_parameters?search=puppetclass_name=motd \
   | python3 -m json.tool

2. Examine the following output. Each Smart Class Parameter has an ID that is global for the same Satellite instance. The content parameter of the motd class has id=3. Do not confuse this with the Puppet Class ID that displays before the Puppet Class name.

   Example response:

   {
   	"avoid_duplicates": false,
   		"created_at": "2024-02-06 12:37:48 UTC", # Remove this line.
   			"default_value": "", # Add a new value here.
   			"description": "",
   		"hidden_value": "",
   		"hidden_value?": false,
   		"id": 3,
   		"merge_default": false,
   		"merge_overrides": false,
   		"override": false, # Set the override value to true.
   			"override_value_order": "fqdn\nhostgroup\nos\ndomain",
   		"override_values": [], # Remove this line.
   			"override_values_count": 0,
   		"parameter": "content",
   		"parameter_type": "string",
   		"puppetclass_id": 3,
   		"puppetclass_name": "motd",
   		"required": false,
   		"updated_at": "2024-02-07 11:56:55 UTC", # Remove this line.
   			"use_puppet_default": false,
   		"validator_rule": null,
   		"validator_type": ""
   }

3. Use the parameter ID 3 to get the information specific to the motd parameter and redirect the output to a file, for example, output_file.json.

   Example request:

   $ curl \
   --header "Accept:application/json" \
   --header "Content-Type:application/json" \
   --request GET \
   --user My_User_Name:My_Password \
   https://satellite.example.com/api/smart_class_parameters/3 \
   | python3 -m json.tool > output_file.json

4. Copy the file created in the previous step to a new file for editing, for example, changed_file.json:

   $ cp output_file.json changed_file.json

5. Modify the required values in the file. In this example, change the content parameter of the motd module, which requires changing the override option from false to true:

   {
   	"avoid_duplicates": false,
   		"created_at": "2024-02-06 12:37:48 UTC", # Remove this line.
   			"default_value": "", # Add a new value here.
   			"description": "",
   		"hidden_value": "",
   		"hidden_value?": false,
   		"id": 3,
   		"merge_default": false,
   		"merge_overrides": false,
   		"override": false, # Set the override value to true.
   			"override_value_order": "fqdn\nhostgroup\nos\ndomain",
   		"override_values": [], # Remove this line.
   			"override_values_count": 0,
   		"parameter": "content",
   		"parameter_type": "string",
   		"puppetclass_id": 3,
   		"puppetclass_name": "motd",
   		"required": false,
   		"updated_at": "2024-02-07 11:56:55 UTC", # Remove this line.
   			"use_puppet_default": false,
   		"validator_rule": null,
   		"validator_type": ""
   }

6. After editing the file, verify that it looks as follows and then save the changes:

   {
   	"avoid_duplicates": false,
   		"default_value": "No Unauthorized Access Allowed",
   			"description": "",
   		"hidden_value": "",
   		"hidden_value?": false,
   		"id": 3,
   		"merge_default": false,
   		"merge_overrides": false,
   		"override": true,
   			"override_value_order": "fqdn\nhostgroup\nos\ndomain",
   		"override_values_count": 0,
   		"parameter": "content",
   		"parameter_type": "string",
   		"puppetclass_id": 3,
   		"puppetclass_name": "motd",
   		"required": false,
   		"use_puppet_default": false,
   		"validator_rule": null,
   		"validator_type": ""
   }

7. Submit the file to Satellite:

   $ curl \
   --header "Accept:application/json" \
   --header "Content-Type:application/json" \
   --request PUT \
   --user My_User_Name:My_Password \
   --data @changed_file.json \
   https://satellite.example.com/api/smart_class_parameters/3

API Procedure

1. List all OpenSCAP reports. Note the IDs of the reports that you want to delete.

   Example request:

   $ curl \
   --user My_User_Name:My_Password \
   https://satellite.example.com/api/v2/compliance/arf_reports/ \
   | python3 -m json.tool

   Example response:

   {
       "page": 1,
       "per_page": 20,
       "results": [
           {
               "created_at": "2024-05-16 13:27:09 UTC",
               "failed": 0,
               "host": "host1.example.com",
               "id": 404,
               "othered": 0,
               "passed": 0,
               "updated_at": "2024-05-16 13:27:09 UTC"
           },
           {
               "created_at": "2024-05-16 13:26:07 UTC",
               "failed": 0,
               "host": "host2.example.com,
               "id": 405,
               "othered": 0,
               "passed": 0,
               "updated_at": "2024-05-16 13:26:07 UTC"
           },
           {
               "created_at": "2024-05-16 13:25:07 UTC",
               "failed": 0,
               "host": "host3.example.com",
               "id": 406,
               "othered": 0,
               "passed": 0,
               "updated_at": "2024-05-16 13:25:07 UTC"
           },
           {
               "created_at": "2024-05-16 13:24:07 UTC",
               "failed": 0,
               "host": "host4.example.com",
               "id": 407,
               "othered": 0,
               "passed": 0,
               "updated_at": "2024-05-16 13:24:07 UTC"
           },
       ],
       "search": null,
       "sort": {
           "by": null,
           "order": null
       },
       "subtotal": 29,
       "total": 29

2. Using an ID from the previous step, delete the OpenSCAP report. Repeat for each ID that you want to delete.

   Example request:

   $ curl \
   --user My_User_Name:My_Password \
   --header "Content-Type: application/json" \
   --request DELETE \
   https://satellite.example.com/api/v2/compliance/arf_reports/405

   Example response:

   HTTP/1.1 200 OK
   Date: Thu, 18 May 2024 07:14:36 GMT
   Server: Apache/2.4.6 (Red Hat Enterprise Linux)
   X-Frame-Options: SAMEORIGIN
   X-XSS-Protection: 1; mode=block
   X-Content-Type-Options: nosniff
   Foreman_version: 3.11.0.76
   Foreman_api_version: 2
   Apipie-Checksum: 2d39dc59aed19120d2359f7515e10d76
   Cache-Control: max-age=0, private, must-revalidate
   X-Request-Id: f47eb877-35c7-41fe-b866-34274b56c506
   X-Runtime: 0.661831
   X-Powered-By: Phusion Passenger 4.0.18
   Set-Cookie: request_method=DELETE; path=/
   Set-Cookie: _session_id=d58fe2649e6788b87f46eabf8a461edd; path=/; secure; HttpOnly
   ETag: "2574955fc0afc47cb5394ce95553f428"
   Status: 200 OK
   Vary: Accept-Encoding
   Transfer-Encoding: chunked
   Content-Type: application/json; charset=utf-8