Introduce API request and API response titles

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-mib.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,20 +1,28 @@
 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_passing-json-data-to-the-api-request.adoc[leveloffset=+2]
 
-include::modules/proc_retrieving-a-list-of-resources.adoc[leveloffset=+2]
+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_calling-the-api-in-ruby.adoc[leveloffset=+1]
+// TODO: Only include parts?
+//       Use tags to mitigate this?
+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/proc_calling-the-api-in-python.adoc[leveloffset=+1]
+include::modules/con_calling-the-api-in-python.adoc[leveloffset=+1]
 
 include::modules/proc_creating-objects-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_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,17 @@
+[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`.
+
+proc_listing-lifecycle-environments
+
+proc_creating-linked-lifecycle-environments
+
+proc_updating-a-lifecycle-environment
+
+proc_deleting-a-lifecycle-environment.adoc

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

@@ -1,11 +1,27 @@
-[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.
+
+[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_"
 ----
+
+[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,33 +1,17 @@
 [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:
+You can use {Project} apply errata to hosts.
+To use the API instead of the {ProjectWebUI}, see the xref:api-applying-errata-to-hosts[].
 
-[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="api-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:
+.Procedure
+. In the {ProjectWebUI}, navigate to *Hosts* > *Host Collections*.
+. Select a host collection.
+. On the *Actions* tab, click *Errata Installation*.
+. Follow the {ProjectWebUI} to install errata.
 
+[id="api-applying-errata-to-hosts"]
+.API procedure
 [options="nowrap", subs="+quotes,attributes"]
 ----
 $ curl \
@@ -38,20 +22,3 @@ $ curl \
 --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="api-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
-----

guides/common/modules/proc_creating-a-user.adoc

@@ -45,5 +45,18 @@ Specifying organization IDs is not required.
 You can modify the user details later by using the `hammer user update` command.
 
 .Additional resources
-
 * For more information about creating user accounts by using Hammer, enter `hammer user create --help`.
+
+[id="api-creating-a-user"]
+.API request
+[options="nowrap", subs="+quotes,attributes"]
+----
+$ curl \
+--header "Accept:application/json" \
+--header "Content-Type:application/json" \
+--request POST \
+--user _My_User_Name_:__My_Password__ \
+--data "{\"firstname\":\"_Test Name_\",\"mail\":\"[email protected]_\",\"login\":\"_test_user_\",\"password\":\"_password123_\",\"auth_source_id\":__1__}" \
+https://_{foreman-example-com}_/api/users \
+| python3 -m json.tool
+----

guides/common/modules/proc_creating-and-modifying-resources.adoc

@@ -4,39 +4,3 @@
 You can use `curl` to manipulate resources on your {ProjectServer}.
 API calls to {Project} require data in `json` format.
 For more information, see xref:passing-json-data-to-the-api-request[].
-
-[id="api-creating-a-user"]
-.Creating a user
-
-This example creates a user by providing required information in the `--data` option.
-
-Example request:
-[options="nowrap", subs="+quotes,attributes"]
-----
-$ curl \
---header "Accept:application/json" \
---header "Content-Type:application/json" \
---request POST \
---user _My_User_Name_:__My_Password__ \
---data "{\"firstname\":\"_Test Name_\",\"mail\":\"[email protected]_\",\"login\":\"_test_user_\",\"password\":\"_password123_\",\"auth_source_id\":__1__}" \
-https://_{foreman-example-com}_/api/users \
-| python3 -m json.tool
-----
-
-[id="api-modifying-a-user"]
-.Modifying a user
-
-This example modifies given name and login of the `test_user` that was created in xref:api-creating-a-user[].
-
-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 "{\"firstname\":\"_New Test Name_\",\"mail\":\"[email protected]_\",\"login\":\"_new_test_user_\",\"password\":\"_password123_\",\"auth_source_id\":__1__}" \
-https://_{foreman-example-com}_/api/users/_8_ \
-| python3 -m json.tool
-----