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

   Copy to Clipboard Toggle word wrap

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

   Example request:

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

   Copy to Clipboard Toggle word wrap

3. Assign the file size to the variable size:

   Example request:

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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

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

   Example request:

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

   Copy to Clipboard Toggle word wrap

5. Assign the upload ID to the variable upload_id:

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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

   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
   }

   Copy to Clipboard Toggle word wrap

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

     Copy to Clipboard Toggle word wrap

   • 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

     Copy to Clipboard Toggle word wrap

     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

     Copy to Clipboard Toggle word wrap

     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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap