第4章 API Requests in Different Languages
This chapter outlines sending API requests to Red Hat Satellite with curl, Ruby, and Python and provides examples.
4.1. API Requests with curl
This section outlines how to use curl with the Satellite API to perform various tasks.
Red Hat Satellite requires the use of HTTPS, and by default a certificate for host identification. If you have not added the Satellite Server certificate as described in 「SSL Authentication Overview」, then you can use the --insecure option to bypass certificate checks.
For user authentication, you can use the --user option to provide Satellite user credentials in the form --user username:password or, if you do not include the password, the command prompts you to enter it. To reduce security risks, do not include the password as part of the command, because it then becomes part of your shell history. Examples in this section include the password only for the sake of simplicity.
Be aware that if you use the --silent option, curl does not display a progress meter or any error messages.
Examples in this chapter use the Python json.tool module to format the output.
4.1.1. Passing JSON Data to the API Request
You can pass data to Satellite Server with the API request. The data must be in JSON format. When specifying JSON data with the --data option, you must set the following HTTP headers with the --header option:
--header "Accept:application/json,version=2" \ --header "Content-Type:application/json"
Use one of the following options to include data with the --data option:
The quoted JSON formatted data enclosed in curly braces
{}. When passing a value for a JSON type parameter, you must escape quotation marks"with backslashes\. For example, within curly braces, you must format"Example JSON Variable"as\"Example JSON Variable\":--data {"id":44, "smart_class_parameter":{"override":"true", "parameter_type":"json", "default_value":"{\"GRUB_CMDLINE_LINUX\": {\"audit\":\"1\",\"crashkernel\":\"true\"}}"}}The unquoted JSON formatted data enclosed in a file and specified by the
@sign and the filename. For example:--data @file.jsonUsing external files for JSON formatted data has the following advantages:
- You can use your favorite text editor.
- You can use syntax checker to find and avoid mistakes.
- You can use tools to check the validity of JSON data or to reformat it.
Validating a JSON file
Use the json_verify tool to check the validity of a JSON file:
$ json_verify < test_file.json4.1.2. Retrieving a List of Resources
This section outlines how to use curl with the Satellite 6 API to request information from your Satellite deployment. These examples include both requests and responses. Expect different results for each deployment.
Listing Users
This example is a basic request that returns a list of Satellite resources, Satellite users in this case. Such requests return a list of data wrapped in metadata, while other request types only return the actual object.
Example request:
$ curl --request GET --insecure --user sat_username:sat_password \ https://satellite.example.com/api/users | python -m json.tool
Example response:
{
"page": 1,
"per_page": 20,
"results": [
{
"admin": false,
"auth_source_id": 1,
"auth_source_name": "Internal",
"created_at": "2018-09-21 08:59:22 UTC",
"default_location": null,
"default_organization": null,
"description": "",
"effective_admin": false,
"firstname": "",
"id": 5,
"last_login_on": "2018-09-21 09:03:25 UTC",
"lastname": "",
"locale": null,
"locations": [],
"login": "test",
"mail": "example@domain.com",
"organizations": [
{
"id": 1,
"name": "Default Organization"
}
],
"ssh_keys": [],
"timezone": null,
"updated_at": "2018-09-21 09:04:45 UTC"
},
{
"admin": true,
"auth_source_id": 1,
"auth_source_name": "Internal",
"created_at": "2018-09-20 07:09:41 UTC",
"default_location": null,
"default_organization": {
"description": null,
"id": 1,
"name": "Default Organization",
"title": "Default Organization"
},
"description": "",
"effective_admin": true,
"firstname": "Admin",
"id": 4,
"last_login_on": "2018-12-07 07:31:09 UTC",
"lastname": "User",
"locale": null,
"locations": [
{
"id": 2,
"name": "Default Location"
}
],
"login": "admin",
"mail": "root@example.com",
"organizations": [
{
"id": 1,
"name": "Default Organization"
}
],
"ssh_keys": [],
"timezone": null,
"updated_at": "2018-11-14 08:19:46 UTC"
}
],
"search": null,
"sort": {
"by": null,
"order": null
},
"subtotal": 2,
"total": 2
}4.1.3. Creating and Modifying Resources
This section outlines how to use curl with the Satellite 6 API to manipulate resources on the Satellite Server. These API calls require that you pass data in json format with the API call. For more information, see 「Passing JSON Data to the API Request」.
Creating a User
This example creates a user using --data option to provide required information.
Example request:
$ curl --header "Accept:application/json,version=2" \ --header "Content-Type:application/json" --request POST \ --user sat_username:sat_password --insecure \ --data "{\"firstname\":\"Test Name\",\"mail\":\"test@example.com\",\"login\":\"test_user\",\"password\":\"password123\",\"auth_source_id\":1}" \ https://satellite.example.com/api/users | python -m json.tool
Modifying a User
This example modifies first name and login of the test_user that was created in Creating a User.
Example request:
$ curl --header "Accept:application/json,version=2" \ --header "Content-Type:application/json" --request PUT \ --user sat_username:sat_password --insecure \ --data "{\"firstname\":\"New Test Name\",\"mail\":\"test@example.com\",\"login\":\"new_test_user\",\"password\":\"password123\",\"auth_source_id\":1}" \ https://satellite.example.com/api/users/8 | python -m json.tool