From 56b197fffc483a16990553bf37452afb7b0f031d Mon Sep 17 00:00:00 2001 From: Zuzana Lena Ansorgova Date: Tue, 13 Aug 2024 01:01:43 +0200 Subject: [PATCH] Upstreamize manually --- guides/doc-Project_API/docinfo.xml | 2 +- guides/doc-Project_API/master.adoc | 2 +- .../doc-Project_API/topics/API_Reference.adoc | 11 +++++-- .../doc-Project_API/topics/Introduction.adoc | 15 +++------ .../topics/PermissionMatrix.adoc | 3 +- .../topics/Response_Codes.adoc | 2 +- .../Understanding_JSON_Response_Format.adoc | 22 ++++++------- .../topics/Understanding_the_API.adoc | 12 +++---- ... Uploading_Content_to_Project_Server.adoc} | 33 +++++++++---------- .../topics/Using_Extended_Searches.adoc | 2 +- .../Using_the_Red_Hat_Satellite_API.adoc | 6 ++-- .../topics/snip_note-python3-vs-python.adoc | 2 +- 12 files changed, 55 insertions(+), 57 deletions(-) rename guides/doc-Project_API/topics/{Uploading_Content_to_Satellite_Server.adoc => Uploading_Content_to_Project_Server.adoc} (87%) diff --git a/guides/doc-Project_API/docinfo.xml b/guides/doc-Project_API/docinfo.xml index bc18238b40c..f423515c9da 100644 --- a/guides/doc-Project_API/docinfo.xml +++ b/guides/doc-Project_API/docinfo.xml @@ -1,4 +1,4 @@ -API Guide +{APIDocTitle} Red Hat Satellite {ProjectVersion} Develop custom applications or integrations by using the Satellite REST API diff --git a/guides/doc-Project_API/master.adoc b/guides/doc-Project_API/master.adoc index ce271c11f74..255ceedd023 100644 --- a/guides/doc-Project_API/master.adoc +++ b/guides/doc-Project_API/master.adoc @@ -3,7 +3,7 @@ include::common/header.adoc[] :context: rest-api :rest-api: -= API Guide += {APIDocTitle} include::common/modules/proc_providing-feedback-on-red-hat-documentation.adoc[leveloffset=+1] diff --git a/guides/doc-Project_API/topics/API_Reference.adoc b/guides/doc-Project_API/topics/API_Reference.adoc index c6ae39b851e..1ba80aa8bac 100644 --- a/guides/doc-Project_API/topics/API_Reference.adoc +++ b/guides/doc-Project_API/topics/API_Reference.adoc @@ -1,7 +1,14 @@ [[chap-Red_Hat_Satellite-API_Guide-API_Reference]] -== API reference +== API syntax -The full API reference is available on your {ProjectServer} at `https://_{foreman-example-com}_/apidoc/v2.html`. Be aware that even though versions 1 and 2 of the {ProjectX} API are available, Red{nbsp}Hat only supports version 2. +[IMPORTANT] +==== +Even though versions 1 and 2 of the {ProjectX} API are available, Red{nbsp}Hat only supports version 2. +==== + +=== Accessing the API reference + +The full API reference is available on your {ProjectServer} at `https://_{foreman-example-com}_/apidoc/v2.html`. include::Understanding_the_API.adoc[] diff --git a/guides/doc-Project_API/topics/Introduction.adoc b/guides/doc-Project_API/topics/Introduction.adoc index 5574e84d7a4..23d43119f14 100644 --- a/guides/doc-Project_API/topics/Introduction.adoc +++ b/guides/doc-Project_API/topics/Introduction.adoc @@ -4,24 +4,19 @@ {ProjectName} provides a Representational State Transfer (REST) API. The API provides software developers and system administrators with control over their {ProjectName} environment outside of the standard web interface. The REST API is useful for developers and administrators who aim to integrate the functionality of {ProjectName} with custom scripts or external applications that access the API over HTTP. [[sect-Red_Hat_Satellite-API_Guide-Overview_of_the_Red_Hat_Satellite_API]] -=== Overview of the {ProjectName} API +=== Overview of the {Project} API The benefits of using the REST API are: -* Broad client support — any programming language, framework, or system with support for HTTP protocol can use the API. - -* Self-descriptive — client applications require minimal knowledge of the {ProjectName} infrastructure because a user discovers many details at runtime. - -* Resource-based model — the resource-based REST model provides a natural way to manage a virtualization platform. +* Broad client support {endash} any programming language, framework, or system with support for HTTP protocol can use the API. +* Self-descriptive {endash} client applications require minimal knowledge of the {ProjectName} infrastructure because a user discovers many details at runtime. +* Resource-based model {endash} the resource-based REST model provides a natural way to manage a virtualization platform. You can use the REST API to perform the following tasks: * Integrate with enterprise IT systems. - * Integrate with third-party applications. - * Perform automated maintenance or error checking tasks. - * Automate repetitive tasks with scripts. As you prepare to upgrade {ProjectServer}, ensure that any scripts you use that contain {Project} API commands are up to date. API commands differ between versions of {Project}. @@ -35,4 +30,4 @@ For many tasks, you can use both Hammer and {Project} API. You can use Hammer as In the background, each Hammer command first establishes a binding to the API and then sends a request. This can have performance implications when executing a large number of Hammer commands in sequence. In contrast, scripts that use API commands communicate directly with the {Project} API. -Note that you must manually update scripts that use API commands, while Hammer automatically reflects changes in the API. For more information, see the link:{BaseURL}hammer_cli_guide/[Hammer CLI Guide]. +Note that you must manually update scripts that use API commands, while Hammer automatically reflects changes in the API. For more information, see the link:{HammerDocURL}[_{HammerDocTitle}_]. diff --git a/guides/doc-Project_API/topics/PermissionMatrix.adoc b/guides/doc-Project_API/topics/PermissionMatrix.adoc index 458940bdecb..464cd7661ee 100644 --- a/guides/doc-Project_API/topics/PermissionMatrix.adoc +++ b/guides/doc-Project_API/topics/PermissionMatrix.adoc @@ -7,7 +7,7 @@ The {ProjectNameX} API supports numerous actions, many of which require specific permissions. The following table lists the API permission names, the actions associated with those permissions, and the associated resource type. .API permissions matrix -[options="header"] +[cols="6,7,1" options="header"] |==== |Permission Name |Actions |Resource Type |view_activation_keys a| @@ -3214,7 +3214,6 @@ The {ProjectNameX} API supports numerous actions, many of which require specific |Katello::SyncPlan -| |my_organizations a| * katello/api/rhsm/candlepin_proxies/list_owners diff --git a/guides/doc-Project_API/topics/Response_Codes.adoc b/guides/doc-Project_API/topics/Response_Codes.adoc index 2769d7e9023..4ef7600434b 100644 --- a/guides/doc-Project_API/topics/Response_Codes.adoc +++ b/guides/doc-Project_API/topics/Response_Codes.adoc @@ -7,7 +7,7 @@ The {ProjectNameX} API provides HTTP response status codes for API calls. The following codes are common for all resources in the {Project} API. .API response codes -[options="header"] +[cols="2,5" options="header"] |==== |Response |Explanation |200 OK |For a successful request action: show, index, update, or delete (GET, PUT, DELETE requests). diff --git a/guides/doc-Project_API/topics/Understanding_JSON_Response_Format.adoc b/guides/doc-Project_API/topics/Understanding_JSON_Response_Format.adoc index f5d5123ae55..5371ebfc335 100644 --- a/guides/doc-Project_API/topics/Understanding_JSON_Response_Format.adoc +++ b/guides/doc-Project_API/topics/Understanding_JSON_Response_Format.adoc @@ -1,5 +1,5 @@ [[sect-API_Guide-Understanding_the_JSON_Response_Format]] -=== Understanding the JSON response format +=== JSON response format Calls to the API return results in JSON format. The API call returns the result for a single-option response or for responses collections. @@ -87,22 +87,22 @@ Example response: .The response metadata fields API response uses the following metadata fields: -* `total` — The total number of objects without any search parameters. +* `total` {endash} The total number of objects without any search parameters. -* `subtotal` — The number of objects returned with the given search parameters. If there is no search, then subtotal is equal to total. +* `subtotal` {endash} The number of objects returned with the given search parameters. If there is no search, then subtotal is equal to total. -* `page` — The page number. +* `page` {endash} The page number. -* `per_page` — The maximum number of objects returned per page. +* `per_page` {endash} The maximum number of objects returned per page. -* `limit` — The specified number of objects to return in a collection response. +* `limit` {endash} The specified number of objects to return in a collection response. -* `offset` — The number of objects skipped before returning a collection. +* `offset` {endash} The number of objects skipped before returning a collection. -* `search` — The search string based on `scoped_scoped` syntax. +* `search` {endash} The search string based on `scoped_scoped` syntax. * `sort` -** `by` — Specifies by what field the API sorts the collection. -** `order` — The sort order, either ASC for ascending or DESC for descending. +** `by` {endash} Specifies by what field the API sorts the collection. +** `order` {endash} The sort order, either ASC for ascending or DESC for descending. -* `results` — The collection of objects. +* `results` {endash} The collection of objects. diff --git a/guides/doc-Project_API/topics/Understanding_the_API.adoc b/guides/doc-Project_API/topics/Understanding_the_API.adoc index 255d5e219ed..b918d158668 100644 --- a/guides/doc-Project_API/topics/Understanding_the_API.adoc +++ b/guides/doc-Project_API/topics/Understanding_the_API.adoc @@ -1,5 +1,5 @@ [[sect-API_Guide-Understanding_the_API_Syntax]] -=== Understanding the API syntax +=== API request composition include::snip_note-python3-vs-python.adoc[] @@ -32,7 +32,7 @@ _API_ROUTE_ \ <7> <7> Use the API route in the following format: `https://_{foreman-example-com}_/katello/api/activation_keys`. In {ProjectX}, version 2 of the API is the default. Therefore it is not necessary to use `v2` in the URL for API calls. <8> Redirect the output to the Python `json.tool` module to make the output easier to read. -==== Using the GET HTTP verb +=== Using the GET HTTP verb Use the GET HTTP verb to get data from the API about an existing entry or resource. @@ -65,7 +65,7 @@ _output truncated_ ---- The response from the API indicates that there are two results in total, this is the first page of the results, and the maximum results per page is set to 20. For more information, see xref:sect-API_Guide-Understanding_the_JSON_Response_Format[]. -==== Using the POST HTTP verb +=== Using the POST HTTP verb Use the POST HTTP verb to submit data to the API to create an entry or resource. You must submit the data in JSON format. For more information, see xref:sect-API_Guide-Passing_JSON_Data_with_the_API_Request[]. @@ -137,7 +137,7 @@ Example response: . Verify that the new activation key is present. In the {ProjectWebUI}, navigate to *Content* > *Activation keys* to view your activation keys. -==== Using the PUT HTTP verb +=== Using the PUT HTTP verb Use the PUT HTTP verb to change an existing value or append to an existing resource. You must submit the data in JSON format. For more information, see xref:sect-API_Guide-Passing_JSON_Data_with_the_API_Request[]. @@ -209,7 +209,7 @@ Example response: . In the {ProjectWebUI}, verify the changes by navigating to *Content* > *Activation keys*. -==== Using the DELETE HTTP verb +=== Using the DELETE HTTP verb To delete a resource, use the DELETE verb with an API route that includes the ID of the resource you want to delete. @@ -241,7 +241,7 @@ _output omitted_ _output truncated_ ---- -==== Relating API error messages to the API reference +=== Relating API error messages to the API reference The API uses a RAILs format to indicate an error: diff --git a/guides/doc-Project_API/topics/Uploading_Content_to_Satellite_Server.adoc b/guides/doc-Project_API/topics/Uploading_Content_to_Project_Server.adoc similarity index 87% rename from guides/doc-Project_API/topics/Uploading_Content_to_Satellite_Server.adoc rename to guides/doc-Project_API/topics/Uploading_Content_to_Project_Server.adoc index 8a3260be92e..68b1dc5aa24 100644 --- a/guides/doc-Project_API/topics/Uploading_Content_to_Satellite_Server.adoc +++ b/guides/doc-Project_API/topics/Uploading_Content_to_Project_Server.adoc @@ -1,17 +1,16 @@ -[id="sect-API_Guide-Uploading_Content_to_the_{Project}_Server"] -=== Uploading content to the {ProjectServer} +[id="sect-API_Guide-Uploading_Content_to_{Project}_Server"] +=== Uploading content to {ProjectServer} -This section outlines how to use the {ProjectX} API to upload and import large files to your {ProjectServer}. This process involves four steps: +You can use the {Project} API to upload and import large files to your {ProjectServer}. +This process involves four steps: . Create an upload request. - . Upload the content. - . Import the content. - . Delete the upload request. -The maximum file size that you can upload is 2MB. For information about uploading larger content, see xref:exam-API_Guide-Uploading_Content_Larger_than_2_MB[]. +The maximum file size that you can upload is 2{nbsp}MB. +For information about uploading larger content, see xref:exam-API_Guide-Uploading_Content_Larger_than_2_MB[]. [id="proc-API_Guide-Uploading_Content_to_the_{Project}_Server"] .Procedure @@ -50,8 +49,8 @@ Example request: [options="nowrap", subs="+quotes,attributes"] ---- $ curl -H 'Content-Type: application/json' -X POST -k \ --u _sat_username:sat_password_ -d "{\"size\": \"$size\", \ -\"checksum\":\"$checksum\"}" \ +-u _sat_username:sat_password_ \ +-d "{\"size\": \"$size\", \"checksum\":\"$checksum\"}" \ https://$(hostname -f)/katello/api/v2/repositories/76/content_uploads ---- + @@ -66,8 +65,6 @@ Example request: . Assign the upload ID to the variable `upload_id`: + -Example request: -+ [options="nowrap", subs="+quotes,attributes"] ---- $ export upload_id=37eb5900-597e-4ac3-9bc5-2250c302fdc4 @@ -91,7 +88,7 @@ Example request: ---- $ curl -u _sat_username:sat_password_ -H Accept:application/json -H \ Content-Type:multipart/form-data -X PUT --data-urlencode size=$size --data-urlencode offset=0 \ ---data-urlencode content@${path} \ +--data-urlencode content@$\{path} \ https://$(hostname -f)/katello/api/v2/repositories/76/content_uploads/$upload_id ---- @@ -206,7 +203,7 @@ $ export path=/root/tmp/bpftool . Upload the file chunks. The offset starts at 0 for the first chunk and increases by 2000000 for each file. Note the use of the offset parameter and how it relates to the file size. -Note also that the indexes are used after the path variable, for example, ${path}0, ${path}1. +Note also that the indexes are used after the path variable, for example, $\{path}0, $\{path}1. + Example requests: + @@ -215,27 +212,27 @@ Example requests: $ curl -u _sat_username:sat_password_ -H Accept:application/json -H \ Content-Type:multipart/form-data \ -X PUT --data-urlencode size=$size --data-urlencode offset=0 \ ---data-urlencode content@${path}0 https://$(hostname -f)/katello/api/v2/repositories/76/content_uploads/$upload_id +--data-urlencode content@$\{path}0 https://$(hostname -f)/katello/api/v2/repositories/76/content_uploads/$upload_id $ curl -u _sat_username:sat_password_ -H Accept:application/json -H \ Content-Type:multipart/form-data \ -X PUT --data-urlencode size=$size --data-urlencode offset=2000000 \ ---data-urlencode content@${path}1 https://$(hostname -f)/katello/api/v2/repositories/76/content_uploads/$upload_id +--data-urlencode content@$\{path}1 https://$(hostname -f)/katello/api/v2/repositories/76/content_uploads/$upload_id $ curl -u _sat_username:sat_password_ -H Accept:application/json -H \ Content-Type:multipart/form-data \ -X PUT --data-urlencode size=$size --data-urlencode offset=4000000 \ ---data-urlencode content@${path}2 https://$(hostname -f)/katello/api/v2/repositories/76/content_uploads/$upload_id +--data-urlencode content@$\{path}2 https://$(hostname -f)/katello/api/v2/repositories/76/content_uploads/$upload_id $curl -u _sat_username:sat_password_ -H Accept:application/json -H \ Content-Type:multipart/form-data \ -X PUT --data-urlencode size=$size --data-urlencode offset=6000000 ---data-urlencode content@${path}3 https://$(hostname -f)/katello/api/v2/repositories/76/content_uploads/$upload_id +--data-urlencode content@$\{path}3 https://$(hostname -f)/katello/api/v2/repositories/76/content_uploads/$upload_id $ curl -u _sat_username:sat_password_ -H Accept:application/json -H \ Content-Type:multipart/form-data \ -X PUT --data-urlencode size=$size --data-urlencode offset=8000000 \ ---data-urlencode content@${path}4 https://$(hostname -f)/katello/api/v2/repositories/76/content_uploads/$upload_id +--data-urlencode content@$\{path}4 https://$(hostname -f)/katello/api/v2/repositories/76/content_uploads/$upload_id ---- . Import the complete upload to the repository: diff --git a/guides/doc-Project_API/topics/Using_Extended_Searches.adoc b/guides/doc-Project_API/topics/Using_Extended_Searches.adoc index 78546ebe0f9..ce25084c3c8 100644 --- a/guides/doc-Project_API/topics/Using_Extended_Searches.adoc +++ b/guides/doc-Project_API/topics/Using_Extended_Searches.adoc @@ -18,7 +18,7 @@ https://_{foreman-example-com}_/api/v2/hosts?search=os_title=\"RedHat+7.7\",mode | python3 -m json.tool ---- + -NOTE: The example request uses `python3` to format the respone from the {ProjectServer}. +NOTE: The example request uses `python3` to format the response from the {ProjectServer}. On RHEL 7 and some older systems, you must use `python` instead of `python3`. + Example response: diff --git a/guides/doc-Project_API/topics/Using_the_Red_Hat_Satellite_API.adoc b/guides/doc-Project_API/topics/Using_the_Red_Hat_Satellite_API.adoc index fb6d783d1bb..8cc9e161320 100644 --- a/guides/doc-Project_API/topics/Using_the_Red_Hat_Satellite_API.adoc +++ b/guides/doc-Project_API/topics/Using_the_Red_Hat_Satellite_API.adoc @@ -1,7 +1,7 @@ [[chap-Red_Hat_Satellite-API_Guide-Using_the_Red_Hat_Satellite_API]] -== Using the {ProjectName} API +== {Project} API cheat sheet -This chapter provides a range of examples of how to use the {ProjectName} API to perform different tasks. You can use the API on {ProjectServer} via HTTPS on port 443, or on {SmartProxyServer} via HTTPS on port 8443. +This chapter provides a range of examples of how to use the {ProjectName} API to perform different tasks. You can use the API on {ProjectServer} via HTTPS on port 443 or on {SmartProxyServer} via HTTPS on port 8443. You can address these different port requirements within the script itself. For example, in Ruby, you can specify the {Project} and {SmartProxy} URLs as follows: @@ -21,7 +21,7 @@ include::Working_with_Hosts.adoc[] include::Working_with_Life_Cycle_Environments.adoc[] -include::Uploading_Content_to_{Project}_Server.adoc[] +include::Uploading_Content_to_Project_Server.adoc[] include::Applying_Errata_to_a_Host_or_Host_Collection.adoc[] diff --git a/guides/doc-Project_API/topics/snip_note-python3-vs-python.adoc b/guides/doc-Project_API/topics/snip_note-python3-vs-python.adoc index 363d2952e1f..85e2c80b8d3 100644 --- a/guides/doc-Project_API/topics/snip_note-python3-vs-python.adoc +++ b/guides/doc-Project_API/topics/snip_note-python3-vs-python.adoc @@ -1,5 +1,5 @@ [NOTE] ==== -The example requests below use `python3` to format the respone from the {ProjectServer}. +The example requests below use `python3` to format the response from the {ProjectServer}. On RHEL 7 and some older systems, you must use `python` instead of `python3`. ====