Introduce API request and API response titles

guides/common/assembly_api-cheat-sheet.adoc

@@ -1,11 +1,39 @@
 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_using-extended-searches.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,18 @@
+[id="working-with-hosts"]
+= Working with hosts
+
+proc_listing-hosts
+
+proc_requesting-information-for-a-host
+
+proc_listing-host-facts
+
+proc_searching-for-hosts-with-matching-patterns
+
+proc_searching-for-hosts-in-an-environment
+
+proc_searching-for-hosts-with-a-specific-fact-value
+
+proc_deleting-a-host
+
+proc_downloading-a-full-host-boot-disk-image

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_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\":\"_test@example.com_\",\"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\":\"_test@example.com_\",\"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\":\"_test@example.com_\",\"login\":\"_new_test_user_\",\"password\":\"_password123_\",\"auth_source_id\":__1__}" \
-https://_{foreman-example-com}_/api/users/_8_ \
-| python3 -m json.tool
-----

guides/common/modules/proc_working-with-lifecycle-environments.adoc → guides/common/modules/proc_creating-linked-lifecycle-environments.adoc

@@ -1,62 +1,11 @@
-[id="working-with-lifecycle-environments"]
-= Working with lifecycle environments
+[id="creating-linked-lifecycle-environments"]
+= Creating linked 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`.
-
-[id="api-listing-lifecycle-environments"]
-.Listing lifecycle environments
-Use this API call to list all the current lifecycle environments on your {Project} for the default organization with ID `1`.
-
-Example request:
-
-[options="nowrap", subs="+quotes,attributes"]
-----
-$ curl \
---header "Accept:application/json" \
---header "Content-Type:application/json" \
---request GET \
---user _My_User_Name_:__My_Password__ \
-https://_{foreman-example-com}_/katello/api/organizations/1/environments \
-| python3 -m json.tool`
-----
-
-Example response:
-
-[source, none, options="nowrap", subs="+quotes,attributes"]
-----
-      _output omitted_
-   "description": null,
-   *"id": 1,*
-   *"label": "Library",*
-   "library": true,
-   *"name": "Library",*
-   "organization": {
-        "id": 1,
-        "label": "Default_Organization",
-        "name": "Default Organization"
-   },
-   "permissions": {
-       "destroy_lifecycle_environments": false,
-       "edit_lifecycle_environments": true,
-       "promote_or_remove_content_views_to_environments": true,
-       "view_lifecycle_environments": true
-   },
-   *"prior": null,*
-   *"successor": null,*
-   _output truncated_
-----
-
-[id="api-creating-linked-lifecycle-environments"]
-.Creating linked lifecycle environments
 Use this example to create a path of lifecycle environments.
-
 This procedure uses the default Library environment with ID `1` as the starting point for creating lifecycle environments.
 
+[id="api-creating-linked-lifecycle-environments"]
+.API procedure
 . Choose an existing lifecycle environment that you want to use as a starting point.
 List the environment by using its ID, in this case, the environment with ID `1`:
 +
@@ -187,68 +136,3 @@ Example response:
 ----
 +
 In the command output, you can see the ID for this lifecycle environment is `3`, and the lifecycle environment before this one is `2`.
-
-[id="api-updating-a-lifecycle-environment"]
-.Updating a lifecycle environment
-
-You can update a lifecycle environment by using a PUT command.
-
-This example request updates a description of the lifecycle environment with ID `3`.
-
-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 '{"description":"Quality Acceptance Testing"}' \
-https://_{foreman-example-com}_/katello/api/environments/3 \
-| python3 -m json.tool
-----
-
-Example response:
-
-[source, none, options="nowrap", subs="+quotes,attributes"]
-----
-      _output omitted_
-    *"description": "Quality Acceptance Testing",*
-    "id": 3,
-    "label": "api-qa",
-    "library": false,
-    "name": "API QA",
-    "organization": {
-        "id": 1,
-        "label": "Default_Organization",
-        "name": "Default Organization"
-    },
-    "permissions": {
-        "destroy_lifecycle_environments": true,
-        "edit_lifecycle_environments": true,
-        "promote_or_remove_content_views_to_environments": true,
-        "view_lifecycle_environments": true
-    },
-    "prior": {
-        "id": 2,
-        "name": "API Development"
-    },
-    _output truncated_
-----
-
-[id="api-deleting-a-lifecycle-environment"]
-.Deleting a lifecycle environment
-
-You can delete a lifecycle environment provided it has no successor.
-Therefore, delete them in reverse order by using a command in the following format:
-
-Example request:
-
-[options="nowrap", subs="+quotes,attributes"]
-----
-$ curl \
---request DELETE \
---user _My_User_Name_:__My_Password__ \
-https://_{foreman-example-com}_/katello/api/environments/_:id_
-----

guides/common/modules/proc_creating-objects-by-using-python.adoc

@@ -5,7 +5,6 @@ This script connects to the {ProjectNameX} API and creates an organization, and
 If the organization already exists, the script uses that organization.
 If any of the environments already exist in the organization, the script raises an error and quits.
 
-.Python 3 example
 [source, Python, subs="attributes"]
 ----
 #!/usr/bin/python3

guides/common/modules/proc_deleting-a-host.adoc

@@ -0,0 +1,15 @@
+[id="deleting-a-host"]
+= Deleting a host
+
+This request deletes a host with a name _host1.example.com_.
+
+[id="api-deleting-a-host"]
+.API request
+[options="nowrap", subs="+quotes,attributes"]
+----
+$ curl \
+--request DELETE \
+--user _My_User_Name_:__My_Password__ \
+https://_{foreman-example-com}_/api/v2/hosts/_host1.example.com_ \
+| python3 -m json.tool
+----

guides/common/modules/proc_deleting-a-lifecycle-environment.adoc

@@ -0,0 +1,15 @@
+[id="deleting-a-lifecycle-environment"]
+= Deleting a lifecycle environment
+
+You can delete a lifecycle environment provided it has no successor.
+Therefore, delete them in reverse order by using a command in the following format:
+
+[id="api-deleting-a-lifecycle-environment"]
+.API request
+[options="nowrap", subs="+quotes,attributes"]
+----
+$ curl \
+--request DELETE \
+--user _My_User_Name_:__My_Password__ \
+https://_{foreman-example-com}_/katello/api/environments/_:id_
+----

guides/common/modules/proc_deleting-openscap-reports.adoc

@@ -5,7 +5,8 @@ In {ProjectServer}, you can delete one or more OpenSCAP reports.
 However, when you delete reports, you must delete one page at a time.
 If you want to delete all OpenSCAP reports, use the bash script that follows.
 
-.Procedure
+[id="api-deleting-openscap-reports"]
+.API Procedure
 . List all OpenSCAP reports.
 Note the IDs of the reports that you want to delete.
 +
@@ -112,10 +113,8 @@ Transfer-Encoding: chunked
 Content-Type: application/json; charset=utf-8
 ----
 
+[id="shell-deleting-openscap-reports"]
 .Example BASH script to delete all OpenSCAP reports
-
-Use the following bash script to delete all the OpenSCAP reports:
-
 [source, bash, options="nowrap" subs="+quotes,attributes"]
 ----
 #!/bin/bash