Red Hat Summit Red Hat SummitSupportKonsoleEntwicklerDemo startenKontakt

Dieser Inhalt ist in der von Ihnen ausgewählten Sprache nicht verfügbar.

Chapter 2. API Reference

The full API reference is available on your Satellite Server at https://satellite6.example.com/apidoc/v2.html (replace satellite6.example.com with the host name of your Satellite Server). Be aware that even though versions 1 and 2 of the Satellite 6 API are available, Red Hat only supports version 2.

2.1. Understanding the API Syntax
Link kopieren

The built-in API reference shows the API route, or path, preceded by an HTTP verb: 
HTTP_VERB API_ROUTE
Copy to Clipboard Toggle word wrap
The HTTP verbs used by the API are GET, POST, PUT, and DELETE. See the HOSTS section of the API reference document at http://satellite6.example.com/apidoc/v2/hosts.html for some examples. If you are already familiar with API syntax and the curl command you can skip this section.
To work with the API, construct a command using the API route from the reference document and the command syntax from the documentation for the command. For example, the curl manual page show the following basic syntax: 
curl [options] [URL...]
Copy to Clipboard Toggle word wrap
The options used in this guide include: -X, --request command, where command is an HTTP verb.

Using the GET HTTP Verb

The GET HTTP verb is used to get data from the API about an existing entry or resource.
Combining an example from the API HOSTS section such as GET /api/hosts with the curl syntax results in: 
curl -X GET https://satellite6.example.com/api/hosts
Copy to Clipboard Toggle word wrap
Satellite only supports HTTPS for connecting to the API, and some form of authentication is required.
For a usable example, we must add at least a user name with the -u option, and the -k option to skip SSL peer certificate verification checks: 
$ curl -X GET -k -u sat_username https://satellite6.example.com/api/hostscurl -X GET -k -u sat_username https://satellite6.example.com/api/hostscurl -X GET -k -u sat_username https://satellite6.example.com/api/hostscurl -X GET -k -u sat_username https://satellite6.example.com/api/hostscurl -X GET -k -u sat_username https://satellite6.example.com/api/hosts
Enter host password for user 'sat_username':
{
  "total": 2,
  "subtotal": 2,
  "page": 1,
  "per_page": 20,
  "search": null,
  "sort": {
    "by": null,
    "order": null
  },
  "results":
	output truncated
Copy to Clipboard Toggle word wrap
The above response from the API indicates that there are two results in total, two results are being returned below, this is the first page of the results, and the maximum results per page is set to 20. This is explained more verbosely in Section 2.2, “Understanding the JSON Response Format”.
Some examples in the API reference include terms preceded by a colon in the form :parameter. For example: 
GET /api/hosts/:id
Copy to Clipboard Toggle word wrap
These are API route parameters and must be replaced by an appropriate value. Route parameters start with a colon and end with id.

Note

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.

Using the POST HTTP Verb

The POST HTTP verb is used to submit data to the API to create a new entry or resource. The data must be in JSON format, and can be included inline using the -d, --data option followed by the quoted JSON formatted data enclosed in braces {}. Alternatively, the unquoted JSON formatted data can be enclosed in a file, and specified using the curl command's @ option. For example, -d @file.json.
The advantages of using external files for JSON formatted data include less problems with quoting and escaping, being able to use your favorite editor with syntax checkers to help you find and avoid mistakes, and external tools to check the validity of JSON data or to reformat it. For example, the yajl package contains the json_verify tool and the json_reformat tool.
Using the json_verify tool, you can check the validity of a JSON file as follows: 
$ json_verify < test_file.jsonjson_verify < test_file.jsonjson_verify < test_file.json
Copy to Clipboard Toggle word wrap
The unstructured JSON data returned by an API call can be piped through the python module json.tool: 
curl API_call | python -m json.tool
Copy to Clipboard Toggle word wrap
Alternately, use the json_reformat tool: 
curl API_call | json_reformat
Copy to Clipboard Toggle word wrap
The output format is explained in Section 2.2, “Understanding the JSON Response Format”.
The API Reference includes the following in the Activation keys section: 
POST /katello/api/activation_keys
Copy to Clipboard Toggle word wrap
This is one possible format for a POST /katello/api/activation_keys command: 
curl -X POST -k -u sat_username:sat_password \
-d @file_of_json-formatted_data \
https://satellite6.example.com/katello/api/activation_keys
Copy to Clipboard Toggle word wrap
To see how the POST HTTP verb works, create a test file, for example, activation-key.json, with contents as follows: 
{"organization_id":1, "name":"TestKey", "description":"Just for testing"}
Copy to Clipboard Toggle word wrap
The following example will create a new Activation key by applying the data in the file just created: 
$ curl -H "Accept:application/json,version=2" \
-H "Content-Type:application/json" -X POST \
-u sat_username:sat_password -k \-u sat_username:sat_password -k \-u sat_username:sat_password -k \
-d @activation-key.json \
https://satellite6.example.com/katello/api/activation_keys | json_reformathttps://satellite6.example.com/katello/api/activation_keys | json_reformathttps://satellite6.example.com/katello/api/activation_keys | json_reformat
{
    "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
    }
}
Copy to Clipboard Toggle word wrap
To view this entry in the web UI, navigate to Content Activation keys. Remember to reload the page after any changes.

Using the PUT HTTP Verb

The PUT HTTP verb is used to submit data to the API to update an existing entry or resource. Similarly to the POST API call, the data must be in JSON format, and can be included inline using the -d, --data option followed by the quoted JSON formatted data enclosed in braces {}. Alternatively, the unquoted JSON formatted data can be enclosed in a file, and specified using the curl command's @ option. For example, -d @file.json.
To change an existing value or append to an existing resource use the PUT HTTP verb. The API reference has the following entry for updating an Activation key: 
PUT /katello/api/activation_keys/:id
Copy to Clipboard Toggle word wrap
To update an existing Activation key, use a command in the following format: 
curl -X PUT -k -u sat_username:sat_password \
-d @file_of_json-formatted_data \
https://satellite6.example.com/katello/api/activation_keys/:id
Copy to Clipboard Toggle word wrap
Replace :id with the ID of the Activation key to be updated. Using the PUT command multiple times with the same values will not create multiple entries.
For example, the test Activation key created in the previous example can be updated by editing the file created previously as follows: 
{"organization_id":1, "name":"TestKey", "description":"Just for testing","max_hosts":"10" }
Copy to Clipboard Toggle word wrap
Use a command as follows to apply the changes in the JSON file: 
$ curl -H "Accept:application/json,version=2" \
-H "Content-Type:application/json" -X PUT \
-u sat_username:sat_password -k \-u sat_username:sat_password -k \-u sat_username:sat_password -k \
-d @activation-key.json \
https://satellite6.example.com/katello/api/activation_keys/2https://satellite6.example.com/katello/api/activation_keys/2https://satellite6.example.com/katello/api/activation_keys/2
{
    "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
    }
}
Copy to Clipboard Toggle word wrap

Using the DELETE HTTP Verb

To delete a resource, use the DELETE verb with an API route that includes the ID of the resource to be deleted.
To delete an existing Activation key, use a command in the following format: 
curl -X DELETE -k -u sat_username:sat_password \
https://satellite6.example.com/katello/api/activation_keys/:id
Copy to Clipboard Toggle word wrap
Replace :id with the ID of the Activation key to be deleted. For example: 
$ curl -H "Accept:application/json,version=2" \
-H "Content-Type:application/json" -X DELETE \
-u admin:RedHat1! -k \
https://satellite6.example.com/katello/api/activation_keys/2 | json_reformat
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
Copy to Clipboard Toggle word wrap

Relating API Error Messages to the API Reference

The API uses a RAILs format to indicate an error: 
Nested_Resource.Attribute_Name
Copy to Clipboard Toggle word wrap
This translates to the following format used in the API reference: 
Resource[Nested_Resource_attributes][Attribute_Name_id]
Copy to Clipboard Toggle word wrap
Nach oben
Red Hat logoGithubredditYoutubeTwitter

Lernen

Testen, kaufen und verkaufen

Communitys

Über Red Hat Dokumentation

Wir helfen Red Hat Benutzern, mit unseren Produkten und Diensten innovativ zu sein und ihre Ziele zu erreichen – mit Inhalten, denen sie vertrauen können. Entdecken Sie unsere neuesten Updates.

Mehr Inklusion in Open Source

Red Hat hat sich verpflichtet, problematische Sprache in unserem Code, unserer Dokumentation und unseren Web-Eigenschaften zu ersetzen. Weitere Einzelheiten finden Sie in Red Hat Blog.

Über Red Hat

Wir liefern gehärtete Lösungen, die es Unternehmen leichter machen, plattform- und umgebungsübergreifend zu arbeiten, vom zentralen Rechenzentrum bis zum Netzwerkrand.

Theme

© 2025 Red Hat