Modularize Foreman API guide

guides/common/assembly_api-cheat-sheet.adoc

@@ -1,17 +1,49 @@
 include::modules/con_api-cheat-sheet.adoc[]
 
-include::modules/proc_working-with-hosts.adoc[leveloffset=+1]
+include::modules/con_working-with-hosts.adoc[leveloffset=+1]
 
-include::modules/proc_working-with-lifecycle-environments.adoc[leveloffset=+1]
+include::modules/proc_listing-hosts.adoc[leveloffset=+2]
+
+include::modules/proc_requesting-information-for-a-host.adoc[leveloffset=+2]
+
+include::modules/proc_listing-host-facts.adoc[leveloffset=+2]
+
+include::modules/proc_searching-for-hosts-with-matching-patterns.adoc[leveloffset=+2]
+
+include::modules/proc_searching-for-hosts-in-an-environment.adoc[leveloffset=+2]
+
+include::modules/proc_searching-for-hosts-with-a-specific-fact-value.adoc[leveloffset=+2]
+
+include::modules/proc_deleting-a-host.adoc[leveloffset=+2]
+
+include::modules/proc_downloading-a-full-host-boot-disk-image.adoc[leveloffset=+2]
+
+include::modules/con_working-with-lifecycle-environments.adoc[leveloffset=+1]
+
+include::modules/proc_listing-lifecycle-environments.adoc[leveloffset=+2]
+
+include::modules/proc_creating-linked-lifecycle-environments.adoc[leveloffset=+2]
+
+include::modules/proc_updating-a-lifecycle-environment.adoc[leveloffset=+2]
+
+include::modules/proc_deleting-a-lifecycle-environment.adoc[leveloffset=+2]
 
 include::modules/proc_uploading-content-to-projectserver.adoc[leveloffset=+1]
 
+include::modules/proc_uploading-content-larger-than-2-mb.adoc[leveloffset=+2]
+
+include::modules/proc_uploading-duplicate-content.adoc[leveloffset=+2]
+
 include::modules/proc_applying-errata-to-hosts.adoc[leveloffset=+1]
 
+include::modules/proc_applying-errata-to-a-host-collection.adoc[leveloffset=+1]
+
 include::modules/proc_using-extended-searches.adoc[leveloffset=+1]
 
 include::modules/proc_using-searches-with-pagination-control.adoc[leveloffset=+1]
 
+include::modules/proc_returning-multiple-pages.adoc[leveloffset=+2]
+
 include::modules/proc_overriding-smart-class-parameters.adoc[leveloffset=+1]
 
 include::modules/proc_modifying-a-smart-class-parameter-by-using-an-external-file.adoc[leveloffset=+1]

guides/common/assembly_api-requests-in-various-languages.adoc

@@ -1,7 +1,27 @@
 include::modules/con_api-requests-in-various-languages.adoc[]
 
-include::modules/proc_calling-the-api-in-curl.adoc[leveloffset=+1]
+include::modules/con_calling-the-api-in-curl.adoc[leveloffset=+1]
 
-include::modules/proc_calling-the-api-in-ruby.adoc[leveloffset=+1]
+include::modules/proc_passing-json-data-to-the-api-request.adoc[leveloffset=+2]
 
-include::modules/proc_calling-the-api-in-python.adoc[leveloffset=+1]
+include::modules/con_retrieving-a-list-of-resources.adoc[leveloffset=+2]
+
+include::modules/proc_listing-users.adoc[leveloffset=+3]
+
+include::modules/proc_creating-and-modifying-resources.adoc[leveloffset=+2]
+
+include::modules/proc_creating-a-user.adoc[leveloffset=+2]
+
+include::modules/proc_modifying-a-user.adoc[leveloffset=+2]
+
+include::modules/con_calling-the-api-in-ruby.adoc[leveloffset=+1]
+
+include::modules/proc_creating-objects-by-using-ruby.adoc[leveloffset=+2]
+
+include::modules/proc_using-apipie-bindings-with-ruby.adoc[leveloffset=+2]
+
+include::modules/con_calling-the-api-in-python.adoc[leveloffset=+1]
+
+include::modules/proc_creating-objects-by-using-python.adoc[leveloffset=+2]
+
+include::modules/proc_retrieving-resource-information-by-using-python.adoc[leveloffset=+2]

guides/common/assembly_api-syntax.adoc

@@ -10,6 +10,12 @@ include::modules/proc_using-the-put-http-method.adoc[leveloffset=+2]
 
 include::modules/proc_using-the-delete-http-method.adoc[leveloffset=+2]
 
-include::modules/ref_json-response-format.adoc[leveloffset=+1]
+include::modules/con_json-response-format.adoc[leveloffset=+1]
+
+include::modules/ref_json-response-format-for-single-objects.adoc[leveloffset=+2]
+
+include::modules/ref_json-response-format-for-collections.adoc[leveloffset=+2]
+
+include::modules/ref_json-response-metadata.adoc[leveloffset=+2]
 
 include::modules/ref_relating-api-error-messages-to-the-api-reference.adoc[leveloffset=+1]

guides/common/modules/con_api-cheat-sheet.adoc

@@ -6,7 +6,7 @@ You can use the API on {ProjectServer} via HTTPS on port 443.
 
 For example, in Ruby, you can specify the {ProjectServer} URL as follows:
 
-[options="nowrap", subs="+quotes,verbatim,attributes"]
+[source, none, options="nowrap", subs="+quotes,verbatim,attributes"]
 ----
 url = 'https://_{foreman-example-com}_/api/v2/'
 ifdef::katello,orcharhino,satellite[]

guides/common/modules/con_api-request-composition.adoc

@@ -3,23 +3,26 @@
 
 The built-in API reference shows the API route, or path, preceded by an HTTP method:
 
+[source, none, options="nowrap", subs="+quotes,attributes"]
 ----
 HTTP_METHOD API_ROUTE
 ----
 
 To work with the API, construct a command by using the `curl` command syntax and the API route from the reference document:
 
+// verify rendered HTML to ensure that the numbers align nicely
 [options="nowrap", subs="+quotes,attributes"]
 ----
-$ curl --request _HTTP_METHOD_ \         #<1>
---insecure \                           #<2>
---user _My_User_Name_:__My_Password__ \      #<3>
---data @_input_file_.json \              #<4>
+$ curl \
+--request _HTTP_METHOD_ \                    #<1>
+--insecure \                               #<2>
+--user _My_User_Name_:__My_Password__ \          #<3>
+--data @_My_Input_File_.json \               #<4>
 --header "Accept:application/json" \       #<5>
 --header "Content-Type:application/json" \ #<5>
---output _output_file_                    #<6>
-_API_ROUTE_ \                             #<7>
-| python3 -m json.tool                  #<8>
+--output _My_Output_File_                    #<6>
+_API_ROUTE_ \                                #<7>
+| python3 -m json.tool                     #<8>
 ----
 
 <1> To use `curl` for the API call, specify an HTTP method with the `--request` option.
@@ -29,9 +32,9 @@ For example, `--request POST`.
 For more information, see xref:ssl-authentication-overview[].
 <3> Provide {Project} user credentials with the `--user` option.
 <4> For `POST` and `PUT` requests, use the `--data` option to pass JSON-formatted data.
-For more information, see xref:sect-API_Guide-Passing_JSON_Data_with_the_API_Request[].
+For more information, see xref:passing-json-data-to-the-api-request[].
 <5> When passing the JSON data with the `--data` option, you must specify the following headers with the `--header` option.
-For more information, see xref:sect-API_Guide-Passing_JSON_Data_with_the_API_Request[].
+For more information, see xref:passing-json-data-to-the-api-request[].
 <6> When downloading content from {ProjectServer}, specify the output file with the `--output` option.
 <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.

guides/common/modules/con_calling-the-api-in-curl.adoc

@@ -0,0 +1,16 @@
+[id="calling-the-api-in-curl"]
+= Calling the API in curl
+
+You can use `curl` with the {Project} API to perform various tasks.
+
+{ProjectName} requires the use of HTTPS, and by default, a certificate for host identification.
+If you have not added the {ProjectServer} certificate as described in xref: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 {Project} user credentials in the form `--user _My_User_Name:_My_Password_`. 
+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.
+For simplicity, the examples in this section include the password.
+
+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.

guides/common/modules/con_calling-the-api-in-python.adoc

@@ -0,0 +1,12 @@
+[id="calling-the-api-in-python"]
+= Calling the API in Python
+
+You can use Python with the {Project} API to perform various tasks.
+
+[IMPORTANT]
+====
+These are example scripts and commands.
+Ensure you review these scripts carefully before use, and replace any variables, user names, passwords, and other information to suit your own deployment.
+====
+
+Example scripts in this section do not use SSL verification for interacting with the REST API.

guides/common/modules/con_calling-the-api-in-ruby.adoc

@@ -0,0 +1,10 @@
+[id="calling-the-api-in-ruby"]
+= Calling the API in Ruby
+
+You can use Ruby with the {Project} API to perform various tasks.
+
+[IMPORTANT]
+====
+These are example scripts and commands.
+Ensure you review these scripts carefully before use, and replace any variables, user names, passwords, and other information to suit your own deployment.
+====

guides/common/modules/con_json-response-format.adoc

@@ -0,0 +1,5 @@
+[id="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.

guides/common/modules/con_retrieving-a-list-of-resources.adoc

@@ -0,0 +1,6 @@
+[id="retrieving-a-list-of-resources"]
+= Retrieving a list of resources
+
+This section outlines how to use `curl` with the {ProjectX} API to request information from {Project}.
+These examples include both requests and responses.
+Expect different results for each deployment.

guides/common/modules/con_working-with-hosts.adoc

@@ -0,0 +1,2 @@
+[id="working-with-hosts"]
+= Working with hosts

guides/common/modules/con_working-with-lifecycle-environments.adoc

@@ -0,0 +1,9 @@
+[id="working-with-lifecycle-environments"]
+= Working with lifecycle environments
+
+{Project} divides application life cycles into lifecycle environments, which represent each stage of the application life cycle.
+Lifecycle environments are linked to from an environment path.
+To create linked lifecycle environments with the API, use the `prior_id` parameter.
+
+You can find the built-in API reference for lifecycle environments at `https://_{foreman-example-com}_/apidoc/v2/lifecycle_environments.html`.
+The API routes include `/katello/api/environments` and `/katello/api/organizations/:organization_id/environments`.

guides/common/modules/proc_accessing-the-built-in-api-reference.adoc

@@ -6,7 +6,7 @@ You can access the full API reference on your {ProjectServer}.
 .Procedure
 * In your browser, access the following URL:
 +
-[options="nowrap", subs="+quotes,attributes"]
+[source, none, options="nowrap", subs="+quotes,attributes"]
 ----
 https://_{foreman-example-com}_/apidoc/v2.html
 ----

guides/common/modules/proc_applying-errata-to-a-host-collection.adoc

@@ -1,11 +1,29 @@
-[id="Applying_Errata_to_a_Host_Collection_{context}"]
+[id="applying-errata-to-a-host-collection"]
 = Applying errata to a host collection
 
-.Using `Remote Execution`
+You can use {Project} to apply errata to a host collection.
+
+ifndef::rest-api[]
+[id="cli-applying-errata-to-a-host-collection"]
+.CLI procedure
 [options="nowrap", subs="+quotes,verbatim,attributes"]
 ----
 # hammer job-invocation create \
 --feature katello_errata_install \
 --inputs errata=_ERRATUM_ID1_,_ERRATUM_ID2_,... \
 --search-query "host_collection = _HOST_COLLECTION_NAME_"
 ----
+endif::[]
+
+[id="api-applying-errata-to-a-host-collection"]
+.API procedure
+[options="nowrap", subs="+quotes,attributes"]
+----
+$ curl \
+--header "Accept:application/json" \
+--header "Content-Type:application/json" \
+--request PUT \
+--user _My_User_Name_:__My_Password__ \
+--data "{\"organization_id\":1,\"included\":{\"search\":\"host_collection=\\\"_my-collection_\\\"\"},\"content_type\":\"errata\",\"content\":[\"_RHBA-2016:1981_\"]}" \
+https://_{foreman-example-com}_/api/v2/hosts/bulk/install_content
+----

guides/common/modules/proc_applying-errata-to-hosts.adoc

@@ -1,49 +1,26 @@
 [id="applying-errata-to-hosts"]
 = Applying errata to hosts
 
-You can use the API to apply errata to a host, host group, or host collection.
-The following is the basic syntax of a PUT request:
-
-[options="nowrap", subs="+quotes,attributes"]
-----
-$ curl --header "Accept:application/json" \
---header "Content-Type:application/json" --request PUT \
---user _My_User_Name_:__My_Password__ \
---data _My_JSON_Formatted_Data_ https://_{foreman-example-com}_
-----
-
-You can browse the built-in API doc to find a URL to use for applying errata.
-You can use the {ProjectWebUI} to help discover the format for the search query.
-Navigate to *Hosts* > *Host Collections* and select a host collection.
-Go to *Collection Actions* > *Errata Installation* and notice the search query box contents.
-For example, for a Host Collection called _my-collection_, the search box contains `host_collection="my-collection"`.
-
-[id="exam-API_Guide-Applying_Errata_to_a_Host"]
-.Applying errata to a host
-
-This example uses the API URL for bulk actions `/katello/api/hosts/bulk/install_content` to show the format required for a simple search.
-
-Example request:
+You can use {Project} apply errata to hosts.
+ifndef::rest-api[]
+To use the API instead of the {ProjectWebUI}, see the xref:api-applying-errata-to-hosts[].
+
+.Procedure
+. In the {ProjectWebUI}, navigate to *Hosts* > *All Hosts*.
+. Select a host.
+. On the *Content* tab, select the *Errata* tab.
+. Select errata and click *Apply*.
+endif::[]
+
+[id="api-applying-errata-to-hosts"]
+.API procedure
 [options="nowrap", subs="+quotes,attributes"]
 ----
-$ curl --header "Accept:application/json" \
---header "Content-Type:application/json" --request PUT \
+$ curl \
+--header "Accept:application/json" \
+--header "Content-Type:application/json" \
+--request PUT \
 --user _My_User_Name_:__My_Password__ \
 --data "{\"organization_id\":1,\"included\":{\"search\":\"_my-host_\"},\"content_type\":\"errata\",\"content\":[\"_RHBA-2016:1981_\"]}" \
 https://_{foreman-example-com}_/api/v2/hosts/bulk/install_content
 ----
-
-[id="exam-API_Guide-Applying_Errata_to_a_Host_Collection"]
-.Applying errata to a host collection
-
-In this example, notice the level of escaping required to pass the search string `host_collection="my-collection"` as seen in the {ProjectWebUI}.
-Example request:
-
-[options="nowrap", subs="+quotes,attributes"]
-----
-$ curl --header "Accept:application/json" \
---header "Content-Type:application/json" --request PUT \
---user _My_User_Name_:__My_Password__ \
---data "{\"organization_id\":1,\"included\":{\"search\":\"host_collection=\\\"_my-collection_\\\"\"},\"content_type\":\"errata\",\"content\":[\"_RHBA-2016:1981_\"]}" \
-https://_{foreman-example-com}_/api/v2/hosts/bulk/install_content
-----