Upstreamize manually

guides/doc-Project_API/docinfo.xml

@@ -1,4 +1,4 @@
-<title>API Guide</title>
+<title>{APIDocTitle}</title>
 <productname>Red Hat Satellite</productname>
 <productnumber>{ProjectVersion}</productnumber>
 <subtitle>Develop custom applications or integrations by using the Satellite REST API</subtitle>

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]
 

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[]
 

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}_].

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

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).

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.

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:
 

guides/doc-Project_API/topics/Uploading_Content_to_Satellite_Server.adoc → 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:

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:

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[]
 

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`.
 ====