Show Table of Contents
4.3. API Examples Using Curl
This section describes how to use
curl to perform various tasks using the Satellite API. The first section describes simple queries, such as listing general host information, searching for facts, and using pattern matching. The second section describes how to modify Satellite resources, with examples of how to upload and import content to your Satellite server.
4.3.1. Performing Simple Queries
The following examples describe how to use
curl to search for information about your Satellite deployment. These examples include both the actual command and some sample output, and example values for user names and passwords. Expect different results for each deployment. These examples also use the python -mjson.tool command to format the output.
Note
Be aware that if you use the
-s (silent) option with curl that you will not see a progress meter or any error messages.
If you use the
-k (insecure) option, you need to use HTTPS and also include the -u (user name) option. You can use the form -u username[:password] or, if you do not include the password, the command prompts you to enter it. Red Hat recommends that you do not include the password as part of the command, because it then becomes part of your shell history and might present a security risk. These examples include the password only for the sake of simplicity.
Retrieving a List of Resources
The following is a basic query that returns a list of resources. Such requests return a list of data wrapped in metadata, while other request types only return the actual object.
$ curl -X GET -s -k -u admin:password https://satellite6.example.com/api/v2/hosts | python -mjson.tool
{
"total" => 2,
"subtotal" => 2,
"page" => 1,
"per_page" => 1000,
"search" => nil,
"sort" => {
"by" => nil,
"order" => nil
},
"results" => [
.
.
.
Running a Generic Host Query
The following query returns information for the host satellite6.example.com:
$ curl -X GET -s -k -u admin:password https://satellite6.example.com/api/v2/hosts/satellite6.example.com | python -mjson.tool
{
"all_puppetclasses": [],
"architecture_id": 1,
"architecture_name": "x86_64",
"build": false,
"capabilities": [
"build"
],
"certname": "satellite6.example.com",
"comment": null,
"compute_profile_id": null,
...Searching for Facts for a Specific Host
The following query returns all facts for the host satellite6.example.com:
$ curl -X GET -s -k -u admin:password https://satellite6.example.com/api/v2/hosts/satellite6.example.com/facts | python -mjson.tool
{
...
"results": {
"satellite6.example.com": {
"augeasversion": "1.0.0",
"bios_release_date": "01/01/2007",
"bios_version": "0.5.1",
"blockdevice_sr0_size": "1073741312",
"facterversion": "1.7.6",
...
}Searching all Hosts for Matching Patterns
The following query returns all hosts that match the pattern "example":
$ curl -X GET -s -k -u admin:password https://satellite6.example.com/api/v2/hosts?search=example | python -mjson.tool
{
...
"results": [
{
"name": "satellite6.example.com",
...
}
],
"search": "example",
}Searching for all Hosts in a Specific Environment
The following query returns all hosts in the "production" environment:
$ curl -X GET -s -k -u admin:password https://satellite6.example.com/api/v2/hosts?search=environment=production | python -mjson.tool
{
...
"results": [
{
"environment_name": "production",
"name": "satellite6.example.com",
...
}
],
"search": "environment=production",
}Searching for all Hosts with a Specific Fact Value
The following query returns all hosts with a model name "RHEV Hypervisor":
$ curl -X GET -s -k -u admin:password https://satellite6.example.com/api/v2/hosts?search=model=\"RHEV+Hypervisor\" | python -mjson.tool
{
...
"results": [
{
"model_id": 1,
"model_name": "RHEV Hypervisor",
"name": "satellite6.example.com",
...
}
],
"search": "model=\"RHEV Hypervisor\"",4.3.2. Creating and Modifying Resources
You can use the Satellite API to manipulate resources on the Satellite server. These API calls require that you pass various parameters beyond the simple user name, password, and URI that you want to query. For example, to upload content to your Satellite server, or to modify Satellite resources, you need to include extra information in the header when you construct your request.
You can specify the version of the API either in the header, as described in the following examples, or as part of the URL. For example, https://satellite6.example.com/api/v2/architectures is the equivalent of using
Accept:version=2 in the request header. The URL specification takes precedence.
Important
If you do not specify an API version, version 1 is used, even though it is not supported. If you specify version 1, you might receive an error message or receive incorrect data. Both of these issues have been addressed upstream and will be available in an upcoming release. Red Hat recommends that you always specify version 2 of the API, either in the header or in the URL.
The following is the basic syntax for a POST request:
$ curl -H "Accept:application/json,version=2" -H "Content-Type:application/json" -X POST -u username[:password] [-k] -d json-formatted-data satellite-url
For example, to create a new architecture, you can use the following example request:
$ curl -H "Accept:application/json,version=2" -H "Content-Type:application/json" -X POST -u admin:changeme -k -d "{\"architecture\":{\"name\":\"i686\"}}" https://satellite6.example.com/api/architectures
This returns output similar to the following:
{"name":"i686","id":3,"created_at":"2015-10-29T13:21:09Z","updated_at":"2015-10-29T13:21:09Z","operatingsystems":[],"images":[]}
You can use the following command to verify that the architecture was created:
$ curl -X GET -u admin:changeme -k https://satellite6.example.com/api/v2/architectures | python -mjson.tool
{
"page": 1,
"per_page": 20,
"results": [
{
"created_at": "2015-04-02T05:29:46Z",
"id": 2,
"name": "i386",
"updated_at": "2015-04-02T05:29:46Z"
},
{
"created_at": "2015-04-02T05:29:46Z",
"id": 1,
"name": "x86_64",
"updated_at": "2015-04-02T05:29:46Z"
},
{
"created_at": "2015-11-04T19:40:15Z",
"id": 3,
"name": "i686",
"updated_at": "2015-11-04T19:40:15Z"
}
],
"search": null,
"sort": {
"by": null,
"order": null
},
"subtotal": 3,
"total": 3
}
You can also use
hammer on the Satellite server to verify the results:
# hammer -u admin -p changeme architecture list ---|------- ID | NAME ---|------- 2 | i386 1 | x86_64 3 | i686 ---|-------
4.3.2.1. Uploading Content to the Satellite Server
Two methods exist for uploading content to your Satellite server. The first method is more straightforward but due to web server configuration limitations, the maximum file size that you can upload is about 30 MB. If you try to upload larger files, the Satellite server returns an error. Satellite 6 supports uploading very large files, but the process is slightly more complex. This section describes how to use
curl with the Satellite 6 API to upload and import large files to your Satellite server. This process involves four steps:
- Create an upload request.
- Upload the content.
- Import the content.
- Delete the upload request.
Creating the Upload Request
The following example command creates an upload request that you can use to upload your content. Ensure you modify the example parameters to suit your deployment:
$ curl -H "Accept:application/json,version=2" -H "Content-Type:application/json" -X POST -u admin:changeme -k -d "{}" https://satellite6.example.com/katello/api/repositories/3/content_uploadsNote
Even though this command uses a POST method, it does not actually pass any data, as evidenced by the empty data string ("{}"). The command creates an
upload_id, but no data is passed to the Satellite server to achieve this.
This command returns output similar to the following:
{"upload_id":"0be156b1-f373-4cad-89d0-924f8f4491d2","_href":"/pulp/api/v2/content/uploads/0be156b1-f373-4cad-89d0-924f8f4491d2/"}
Make a note of the
upload_id value; you need this value when you upload your content to the Satellite server.
Uploading Your Content
Ensure you use the correct MIME type when you upload data. The "application/json" MIME type is used for the majority of requests to Satellite 6.
The following example illustrates how to combine the
upload_id, MIME type, and other parameters to upload content:
$ curl -H "Accept:application/json,version=2" -H "Content-Type:multipart/form-data" -X PUT -u admin:changeme -k --data-urlencode "content@/home/sat6user/rpmbuild/RPMS/noarch/python-scripttest-1.1.1-1.fc21.noarch.rpm" --data-urlencode offset=0 https://satellite6.example.com/katello/api/repositories/3/content_uploads/0be156b1-f373-4cad-89d0-924f8f4491d2
You can make this request multiple times to upload large files. Break the content into smaller pieces (for example, 5 MB, using a tool such as
split), and increment the offset in bytes.
Importing the Uploaded Content
After you have uploaded the content to the Satellite server, you need to import it into the appropriate repository. Until you complete this step, the Satellite server will not be aware of the new content.
$ curl -H "Accept:application/json,version=2" -H "Content-Type:application/json" -X PUT -u admin:changeme -k -d "{\"upload_ids\":[\"0be156b1-f373-4cad-89d0-924f8f4491d2\"]}" https://satellite6.example.com>/katello/api/repositories/3/import_uploadsDeleting the Upload Request
After you have successfully uploaded and imported your content, you can delete the upload request. This frees any temporary disk space that was used during the upload.
$ curl -H "Accept:application/json,version=2" -H "Content-Type:application/json" -X DELETE -d "{}" -u admin:changeme -k https://satellite6.example.com/katello/api/repositories/3/content_uploads/0be156b1-f373-4cad-89d0-924f8f4491d24.3.2.1.1. Complete Example of Uploading Content
The following example demonstrates in full how to split a large file into chunks, create an upload request, upload the individual files, import them to Satellite, and then delete the upload request. Note that this example uses sample content, host names, user names, and file names.
- Download the sample module and split it into 50.000 byte chunks.
$ wget https://forgeapi.puppetlabs.com/v3/files/theforeman-foreman-5.0.1.tar.gz?_ga=1.267255502.1792403825.1430297670 -O theforeman-foreman-5.0.1.tar.gz $ split --bytes 50000 --numeric-suffixes --suffix-length=1 theforeman-foreman-5.0.1.tar.gz foreman_module. $ ls -la theforeman-foreman-5.0.1.tar.gz foreman_module.* -rw-r--r--. 1 root root 50000 Nov 4 04:42 foreman_module.0 -rw-r--r--. 1 root root 32928 Nov 4 04:42 foreman_module.1 -rw-r--r--. 1 root root 82928 Nov 4 04:41 theforeman-foreman-5.0.1.tar.gz
- Create a new upload request (this is the equivalent of
caton the Satellite server.$ curl -H "Accept:application/json,version=2" -H "Content-Type:application/json" -X POST -u admin:changeme -k -d "{}" https://ibm-vm01.example.com/katello/api/repositories/2/content_uploads It responded with upload id: {"upload_id":"9585528f-07ad-4bb1-9c80-ccece249b2b7","_href":"/pulp/api/v2/content/uploads/9585528f-07ad-4bb1-9c80-ccece249b2b7/"} - Upload the file chunks that you created in Step 1. Notice the use of the
offsetparameter in this example and how it relates to the file size.$ curl -H "Accept:application/json,version=2" -H "Content-Type:multipart/form-data" -X PUT -u admin:changeme -k --data-urlencode "content@foreman_module.0" --data-urlencode offset=0 https://ibm-vm01.example.com/katello/api/repositories/2/content_uploads/9585528f-07ad-4bb1-9c80-ccece249b2b7 $ curl -H "Accept:application/json,version=2" -H "Content-Type:multipart/form-data" -X PUT -u admin:changeme -k --data-urlencode "content@foreman_module.1" --data-urlencode offset=50000 https://ibm-vm01.example.com/katello/api/repositories/2/content_uploads/9585528f-07ad-4bb1-9c80-ccece249b2b7
- Import the complete upload to the repository.
$ curl -H "Accept:application/json,version=2" -H "Content-Type:application/json" -X PUT -u admin:changeme -k -d "{\"upload_ids\":[\"9585528f-07ad-4bb1-9c80-ccece249b2b7\"]}" https://ibm-vm01.example.com/katello/api/repositories/2/import_uploads - Delete the upload.
$ curl -H "Accept:application/json,version=2" -H "Content-Type:application/json" -X DELETE -d "{}" -u admin:changeme -k https://ibm-vm01.example.com/katello/api/repositories/2/content_uploads/9585528f-07ad-4bb1-9c80-ccece249b2b7
If you log in to the server you can check that the files match:
$ ls -la /var/lib/pulp/content/puppet_module/theforeman-foreman-5.0.1.tar.gz -rw-r--r--. 1 apache apache 82928 Nov 4 04:55 /var/lib/pulp/content/puppet_module/theforeman-foreman-5.0.1.tar.gz $ cmp /var/lib/pulp/content/puppet_module/theforeman-foreman-5.0.1.tar.gz theforeman-foreman-5.0.1.tar.gz $ echo $? 0
Where did the comment section go?
Red Hat's documentation publication system recently went through an upgrade to enable speedier, more mobile-friendly content. We decided to re-evaluate our commenting platform to ensure that it meets your expectations and serves as an optimal feedback mechanism. During this redesign, we invite your input on providing feedback on Red Hat documentation via the discussion platform.