From bfbb81d84154da9ae2fa2c88a4a9da9d2b9c47a6 Mon Sep 17 00:00:00 2001 From: Maximilian Kolb Date: Thu, 17 Oct 2024 08:54:37 +0200 Subject: [PATCH] Introduce API request and API response titles --- guides/common/assembly_api-cheat-sheet.adoc | 36 ++- ...bly_api-requests-in-various-languages.adoc | 16 +- guides/common/assembly_api-syntax.adoc | 8 +- ....adoc => con_calling-the-api-in-curl.adoc} | 0 ...doc => con_calling-the-api-in-python.adoc} | 0 ....adoc => con_calling-the-api-in-ruby.adoc} | 0 .../modules/con_json-response-format.adoc | 5 + .../con_retrieving-a-list-of-resources.adoc | 6 + .../modules/con_working-with-hosts.adoc | 2 + ...n_working-with-lifecycle-environments.adoc | 17 ++ ..._applying-errata-to-a-host-collection.adoc | 20 +- .../proc_applying-errata-to-hosts.adoc | 51 +--- .../common/modules/proc_creating-a-user.adoc | 15 +- ...proc_creating-and-modifying-resources.adoc | 36 --- ...eating-linked-lifecycle-environments.adoc} | 124 +--------- ...proc_creating-objects-by-using-python.adoc | 1 - .../common/modules/proc_deleting-a-host.adoc | 15 ++ ...proc_deleting-a-lifecycle-environment.adoc | 15 ++ .../proc_deleting-openscap-reports.adoc | 7 +- ...wnloading-a-full-host-boot-disk-image.adoc | 15 ++ .../modules/proc_listing-host-facts.adoc | 31 +++ guides/common/modules/proc_listing-hosts.adoc | 34 +++ .../proc_listing-lifecycle-environments.adoc | 42 ++++ ...resources.adoc => proc_listing-users.adoc} | 18 +- .../common/modules/proc_modifying-a-user.adoc | 18 ++ ...roc_requesting-information-for-a-host.adoc | 33 +++ ...-resource-information-by-using-python.adoc | 1 - .../proc_returning-multiple-pages.adoc | 16 ++ ...searching-for-hosts-in-an-environment.adoc | 32 +++ ...-for-hosts-with-a-specific-fact-value.adoc | 33 +++ ...hing-for-hosts-with-matching-patterns.adoc | 31 +++ ...proc_updating-a-lifecycle-environment.adoc | 46 ++++ ...c_uploading-content-larger-than-2-mib.adoc | 169 +++++++++++++ ...oc_uploading-content-to-projectserver.adoc | 208 ---------------- .../proc_uploading-duplicate-content.adoc | 40 ++++ ...sing-searches-with-pagination-control.adoc | 39 +-- .../proc_using-the-delete-http-method.adoc | 9 +- .../proc_using-the-get-http-method.adoc | 10 +- .../proc_using-the-post-http-method.adoc | 9 +- .../proc_using-the-put-http-method.adoc | 6 +- .../modules/proc_working-with-hosts.adoc | 226 ------------------ ..._json-response-format-for-collections.adoc | 60 +++++ ...on-response-format-for-single-objects.adoc | 31 +++ .../modules/ref_json-response-format.adoc | 110 --------- .../modules/ref_json-response-metadata.adoc | 17 ++ .../modules/ref_oauth-request-format.adoc | 4 +- 46 files changed, 834 insertions(+), 828 deletions(-) rename guides/common/modules/{proc_calling-the-api-in-curl.adoc => con_calling-the-api-in-curl.adoc} (100%) rename guides/common/modules/{proc_calling-the-api-in-python.adoc => con_calling-the-api-in-python.adoc} (100%) rename guides/common/modules/{proc_calling-the-api-in-ruby.adoc => con_calling-the-api-in-ruby.adoc} (100%) create mode 100644 guides/common/modules/con_json-response-format.adoc create mode 100644 guides/common/modules/con_retrieving-a-list-of-resources.adoc create mode 100644 guides/common/modules/con_working-with-hosts.adoc create mode 100644 guides/common/modules/con_working-with-lifecycle-environments.adoc rename guides/common/modules/{proc_working-with-lifecycle-environments.adoc => proc_creating-linked-lifecycle-environments.adoc} (52%) create mode 100644 guides/common/modules/proc_deleting-a-host.adoc create mode 100644 guides/common/modules/proc_deleting-a-lifecycle-environment.adoc create mode 100644 guides/common/modules/proc_downloading-a-full-host-boot-disk-image.adoc create mode 100644 guides/common/modules/proc_listing-host-facts.adoc create mode 100644 guides/common/modules/proc_listing-hosts.adoc create mode 100644 guides/common/modules/proc_listing-lifecycle-environments.adoc rename guides/common/modules/{proc_retrieving-a-list-of-resources.adoc => proc_listing-users.adoc} (89%) create mode 100644 guides/common/modules/proc_modifying-a-user.adoc create mode 100644 guides/common/modules/proc_requesting-information-for-a-host.adoc create mode 100644 guides/common/modules/proc_returning-multiple-pages.adoc create mode 100644 guides/common/modules/proc_searching-for-hosts-in-an-environment.adoc create mode 100644 guides/common/modules/proc_searching-for-hosts-with-a-specific-fact-value.adoc create mode 100644 guides/common/modules/proc_searching-for-hosts-with-matching-patterns.adoc create mode 100644 guides/common/modules/proc_updating-a-lifecycle-environment.adoc create mode 100644 guides/common/modules/proc_uploading-content-larger-than-2-mib.adoc create mode 100644 guides/common/modules/proc_uploading-duplicate-content.adoc delete mode 100644 guides/common/modules/proc_working-with-hosts.adoc create mode 100644 guides/common/modules/ref_json-response-format-for-collections.adoc create mode 100644 guides/common/modules/ref_json-response-format-for-single-objects.adoc delete mode 100644 guides/common/modules/ref_json-response-format.adoc create mode 100644 guides/common/modules/ref_json-response-metadata.adoc diff --git a/guides/common/assembly_api-cheat-sheet.adoc b/guides/common/assembly_api-cheat-sheet.adoc index 5ed140294e4..3a6576426fb 100644 --- a/guides/common/assembly_api-cheat-sheet.adoc +++ b/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] diff --git a/guides/common/assembly_api-requests-in-various-languages.adoc b/guides/common/assembly_api-requests-in-various-languages.adoc index c96fdc71d1d..33954109d28 100644 --- a/guides/common/assembly_api-requests-in-various-languages.adoc +++ b/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] diff --git a/guides/common/assembly_api-syntax.adoc b/guides/common/assembly_api-syntax.adoc index 68411d17459..4ec782b1cbd 100644 --- a/guides/common/assembly_api-syntax.adoc +++ b/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] diff --git a/guides/common/modules/proc_calling-the-api-in-curl.adoc b/guides/common/modules/con_calling-the-api-in-curl.adoc similarity index 100% rename from guides/common/modules/proc_calling-the-api-in-curl.adoc rename to guides/common/modules/con_calling-the-api-in-curl.adoc diff --git a/guides/common/modules/proc_calling-the-api-in-python.adoc b/guides/common/modules/con_calling-the-api-in-python.adoc similarity index 100% rename from guides/common/modules/proc_calling-the-api-in-python.adoc rename to guides/common/modules/con_calling-the-api-in-python.adoc diff --git a/guides/common/modules/proc_calling-the-api-in-ruby.adoc b/guides/common/modules/con_calling-the-api-in-ruby.adoc similarity index 100% rename from guides/common/modules/proc_calling-the-api-in-ruby.adoc rename to guides/common/modules/con_calling-the-api-in-ruby.adoc diff --git a/guides/common/modules/con_json-response-format.adoc b/guides/common/modules/con_json-response-format.adoc new file mode 100644 index 00000000000..6177bd73a5a --- /dev/null +++ b/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. diff --git a/guides/common/modules/con_retrieving-a-list-of-resources.adoc b/guides/common/modules/con_retrieving-a-list-of-resources.adoc new file mode 100644 index 00000000000..69570e08355 --- /dev/null +++ b/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. diff --git a/guides/common/modules/con_working-with-hosts.adoc b/guides/common/modules/con_working-with-hosts.adoc new file mode 100644 index 00000000000..4dd3e7ae004 --- /dev/null +++ b/guides/common/modules/con_working-with-hosts.adoc @@ -0,0 +1,2 @@ +[id="working-with-hosts"] += Working with hosts diff --git a/guides/common/modules/con_working-with-lifecycle-environments.adoc b/guides/common/modules/con_working-with-lifecycle-environments.adoc new file mode 100644 index 00000000000..9a8a36e75e4 --- /dev/null +++ b/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 diff --git a/guides/common/modules/proc_applying-errata-to-a-host-collection.adoc b/guides/common/modules/proc_applying-errata-to-a-host-collection.adoc index 3fda9c80d2b..13fdfef7b40 100644 --- a/guides/common/modules/proc_applying-errata-to-a-host-collection.adoc +++ b/guides/common/modules/proc_applying-errata-to-a-host-collection.adoc @@ -1,7 +1,10 @@ -[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 \ @@ -9,3 +12,16 @@ --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 +---- diff --git a/guides/common/modules/proc_applying-errata-to-hosts.adoc b/guides/common/modules/proc_applying-errata-to-hosts.adoc index abe1ce60912..ae28b62b3e7 100644 --- a/guides/common/modules/proc_applying-errata-to-hosts.adoc +++ b/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 ----- diff --git a/guides/common/modules/proc_creating-a-user.adoc b/guides/common/modules/proc_creating-a-user.adoc index 88009bb0067..e4c2638c4dc 100644 --- a/guides/common/modules/proc_creating-a-user.adoc +++ b/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 +---- diff --git a/guides/common/modules/proc_creating-and-modifying-resources.adoc b/guides/common/modules/proc_creating-and-modifying-resources.adoc index c52a35f899f..9faef4ff3f8 100644 --- a/guides/common/modules/proc_creating-and-modifying-resources.adoc +++ b/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 ----- diff --git a/guides/common/modules/proc_working-with-lifecycle-environments.adoc b/guides/common/modules/proc_creating-linked-lifecycle-environments.adoc similarity index 52% rename from guides/common/modules/proc_working-with-lifecycle-environments.adoc rename to guides/common/modules/proc_creating-linked-lifecycle-environments.adoc index 0c810edf0e1..abae381dbc5 100644 --- a/guides/common/modules/proc_working-with-lifecycle-environments.adoc +++ b/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_ ----- diff --git a/guides/common/modules/proc_creating-objects-by-using-python.adoc b/guides/common/modules/proc_creating-objects-by-using-python.adoc index e051870dfea..10e3b4c8d6e 100644 --- a/guides/common/modules/proc_creating-objects-by-using-python.adoc +++ b/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 diff --git a/guides/common/modules/proc_deleting-a-host.adoc b/guides/common/modules/proc_deleting-a-host.adoc new file mode 100644 index 00000000000..17cad849e51 --- /dev/null +++ b/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 +---- diff --git a/guides/common/modules/proc_deleting-a-lifecycle-environment.adoc b/guides/common/modules/proc_deleting-a-lifecycle-environment.adoc new file mode 100644 index 00000000000..d028d0fa81a --- /dev/null +++ b/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_ +---- diff --git a/guides/common/modules/proc_deleting-openscap-reports.adoc b/guides/common/modules/proc_deleting-openscap-reports.adoc index dbc6f58e83b..8c00f8e4fea 100644 --- a/guides/common/modules/proc_deleting-openscap-reports.adoc +++ b/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 diff --git a/guides/common/modules/proc_downloading-a-full-host-boot-disk-image.adoc b/guides/common/modules/proc_downloading-a-full-host-boot-disk-image.adoc new file mode 100644 index 00000000000..e1dac8f7c0f --- /dev/null +++ b/guides/common/modules/proc_downloading-a-full-host-boot-disk-image.adoc @@ -0,0 +1,15 @@ +[id="downloading-a-full-host-boot-disk-image"] += Downloading a full-host boot disk image + +This request downloads a full boot disk image for a host by its ID. + +[id="api-downloading-a-full-host-boot-disk-image"] +.API request +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl \ +--request GET \ +--user _My_User_Name_:__My_Password__ \ +--output _My_Image_.iso \ +https://_{foreman-example-com}_/api/bootdisk/hosts/_host_ID_?full=true +---- diff --git a/guides/common/modules/proc_listing-host-facts.adoc b/guides/common/modules/proc_listing-host-facts.adoc new file mode 100644 index 00000000000..001b3918883 --- /dev/null +++ b/guides/common/modules/proc_listing-host-facts.adoc @@ -0,0 +1,31 @@ +[id="listing-host-facts"] += Listing host facts + +This request returns all facts for the host `{foreman-example-com}`. + +[id="api-listing-host-facts"] +.API request +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl \ +--request GET \ +--user _My_User_Name_:__My_Password__ \ +https://_{foreman-example-com}_/api/v2/hosts/_{foreman-example-com}_/facts \ +| python3 -m json.tool +---- + +.API response +[source, none, options="nowrap", subs="+quotes,attributes"] +---- +{ + ... + "results": { + "_{foreman-example-com}_": { + "augeasversion": "1.0.0", + "bios_release_date": "01/01/2007", + "bios_version": "0.5.1", + "blockdevice_sr0_size": "1073741312", + "facterversion": "1.7.6", + ... +} +---- diff --git a/guides/common/modules/proc_listing-hosts.adoc b/guides/common/modules/proc_listing-hosts.adoc new file mode 100644 index 00000000000..b691abcb026 --- /dev/null +++ b/guides/common/modules/proc_listing-hosts.adoc @@ -0,0 +1,34 @@ +[id="listing-hosts"] += Listing hosts + +This example returns a list of registered hosts. + +[id="api-listing-hosts"] +.API request +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl \ +--request GET \ +--user _My_User_Name_:__My_Password__ \ +https://_{foreman-example-com}_/api/v2/hosts \ +| python3 -m json.tool +---- + +.API response +[source, none, options="nowrap", subs="+quotes,attributes"] +---- +{ + ... + "total" => 2, + "subtotal" => 2, + "page" => 1, + "per_page" => 1000, + "search" => nil, + "sort" => { + "by" => nil, + "order" => nil + }, + "results" => [ + ... +} +---- diff --git a/guides/common/modules/proc_listing-lifecycle-environments.adoc b/guides/common/modules/proc_listing-lifecycle-environments.adoc new file mode 100644 index 00000000000..4d1b4f8d413 --- /dev/null +++ b/guides/common/modules/proc_listing-lifecycle-environments.adoc @@ -0,0 +1,42 @@ +[id="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`. + +[id="api-listing-lifecycle-environments"] +.API 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` +---- + +.API 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_ +---- diff --git a/guides/common/modules/proc_retrieving-a-list-of-resources.adoc b/guides/common/modules/proc_listing-users.adoc similarity index 89% rename from guides/common/modules/proc_retrieving-a-list-of-resources.adoc rename to guides/common/modules/proc_listing-users.adoc index 202bb4be51c..2f04c244350 100644 --- a/guides/common/modules/proc_retrieving-a-list-of-resources.adoc +++ b/guides/common/modules/proc_listing-users.adoc @@ -1,18 +1,11 @@ -[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. - -[id="api-listing-users"] -.Listing users +[id="listing-users"] += Listing users This example is a basic request that returns a list of {Project} resources, {Project} users in this case. Such requests return a list of data wrapped in metadata, while other request types only return the actual object. -Example request: - +[id="api-listing-users"] +.API request [options="nowrap", subs="+quotes,attributes"] ---- $ curl \ @@ -22,8 +15,7 @@ https://_{foreman-example-com}_/api/users \ | python3 -m json.tool ---- -Example response: - +.API response [source, none, options="nowrap", subs="+quotes,attributes"] ---- { diff --git a/guides/common/modules/proc_modifying-a-user.adoc b/guides/common/modules/proc_modifying-a-user.adoc new file mode 100644 index 00000000000..d9efa3ed5c7 --- /dev/null +++ b/guides/common/modules/proc_modifying-a-user.adoc @@ -0,0 +1,18 @@ +[id="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[]. + +[id="api-modifying-a-user"] +.API 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 +---- diff --git a/guides/common/modules/proc_requesting-information-for-a-host.adoc b/guides/common/modules/proc_requesting-information-for-a-host.adoc new file mode 100644 index 00000000000..2b1d85b543a --- /dev/null +++ b/guides/common/modules/proc_requesting-information-for-a-host.adoc @@ -0,0 +1,33 @@ +[id="requesting-information-for-a-host"] += Requesting information for a host + +This request returns information for the host `{foreman-example-com}`. + +[id="api-requesting-information-for-a-host"] +.API request +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl \ +--request GET \ +--user _My_User_Name_:__My_Password__ \ +https://_{foreman-example-com}_/api/v2/hosts/_{foreman-example-com}_ \ +| python3 -m json.tool +---- + +.API response +[source, none, options="nowrap", subs="+quotes,attributes"] +---- +{ + "all_puppetclasses": [], + "architecture_id": 1, + "architecture_name": "x86_64", + "build": false, + "capabilities": [ + "build" + ], + "certname": "_{foreman-example-com}_", + "comment": null, + "compute_profile_id": null, + ... +} +---- diff --git a/guides/common/modules/proc_retrieving-resource-information-by-using-python.adoc b/guides/common/modules/proc_retrieving-resource-information-by-using-python.adoc index 600b5bdbf86..98b790214cd 100644 --- a/guides/common/modules/proc_retrieving-resource-information-by-using-python.adoc +++ b/guides/common/modules/proc_retrieving-resource-information-by-using-python.adoc @@ -3,7 +3,6 @@ This is an example script that uses Python for various API requests. -.Python 3 example [source, Python, subs="attributes"] ---- #!/usr/bin/env python3 diff --git a/guides/common/modules/proc_returning-multiple-pages.adoc b/guides/common/modules/proc_returning-multiple-pages.adoc new file mode 100644 index 00000000000..42e38a15fe3 --- /dev/null +++ b/guides/common/modules/proc_returning-multiple-pages.adoc @@ -0,0 +1,16 @@ +[id="returning-multiple-pages"] += Returning multiple pages + +You can use a `for` loop structure to get multiple pages of results. +This example returns pages 1 to 3 of Content Views with 5 results per page. + +.Bash script +[source, bash, options="nowrap", subs="+quotes,attributes"] +---- +$ for i in `seq 1 3`; do \ + curl \ + --request GET \ + --user _My_User_Name_:__My_Password__ \ + https://{foreman-example-com}/katello/api/content_views?per_page=5&page=$i; \ +done +---- diff --git a/guides/common/modules/proc_searching-for-hosts-in-an-environment.adoc b/guides/common/modules/proc_searching-for-hosts-in-an-environment.adoc new file mode 100644 index 00000000000..43b9e14ba89 --- /dev/null +++ b/guides/common/modules/proc_searching-for-hosts-in-an-environment.adoc @@ -0,0 +1,32 @@ +[id="searching-for-hosts-in-an-environment"] += Searching for hosts in an environment + +This query returns all hosts in the `production` environment. + +[id="api-searching-for-hosts-in-an-environment"] +.API request +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl \ +--request GET \ +--user _My_User_Name_:__My_Password__ \ +https://_{foreman-example-com}_/api/v2/hosts?search=environment=production \ +| python3 -m json.tool +---- + +.API response +[source, none, options="nowrap", subs="+quotes,attributes"] +---- +{ + ... + "results": [ + { + "environment_name": "production", + "name": "_{foreman-example-com}_", + ... + } + ], + "search": "environment=production", + ... +} +---- diff --git a/guides/common/modules/proc_searching-for-hosts-with-a-specific-fact-value.adoc b/guides/common/modules/proc_searching-for-hosts-with-a-specific-fact-value.adoc new file mode 100644 index 00000000000..84455a477b3 --- /dev/null +++ b/guides/common/modules/proc_searching-for-hosts-with-a-specific-fact-value.adoc @@ -0,0 +1,33 @@ +[id="searching-for-hosts-with-a-specific-fact-value"] += Searching for hosts with a specific fact value + +This query returns all hosts with a model name `RHV Hypervisor`. + +[id="api-searching-for-hosts-with-a-specific-fact-value"] +.API request +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl \ +--request GET \ +--user _My_User_Name_:__My_Password__ \ +https://_{foreman-example-com}_/api/v2/hosts?search=model=\"RHV+Hypervisor\" \ +| python3 -m json.tool +---- + +.API response +[source, none, options="nowrap", subs="+quotes,attributes"] +---- +{ + ... + "results": [ + { + "model_id": 1, + "model_name": "RHV Hypervisor", + "name": "_{foreman-example-com}_", + ... + } + ], + "search": "model=\"RHV Hypervisor\"", + ... +} +---- diff --git a/guides/common/modules/proc_searching-for-hosts-with-matching-patterns.adoc b/guides/common/modules/proc_searching-for-hosts-with-matching-patterns.adoc new file mode 100644 index 00000000000..c48e941bf31 --- /dev/null +++ b/guides/common/modules/proc_searching-for-hosts-with-matching-patterns.adoc @@ -0,0 +1,31 @@ +[id="searching-for-hosts-with-matching-patterns"] += Searching for hosts with matching patterns + +This query returns all hosts that match the pattern "example". + +[id="api-searching-for-hosts-with-matching-patterns"] +.API request +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl \ +--request GET \ +--user _My_User_Name_:__My_Password__ \ +https://_{foreman-example-com}_/api/v2/hosts?search=example \ +| python3 -m json.tool +---- + +.API response +[source, none, options="nowrap", subs="+quotes,attributes"] +---- +{ + ... + "results": [ + { + "name": "_{foreman-example-com}_", + ... + } + ], + "search": "example", + ... +} +---- diff --git a/guides/common/modules/proc_updating-a-lifecycle-environment.adoc b/guides/common/modules/proc_updating-a-lifecycle-environment.adoc new file mode 100644 index 00000000000..8ad5e5499e1 --- /dev/null +++ b/guides/common/modules/proc_updating-a-lifecycle-environment.adoc @@ -0,0 +1,46 @@ +[id="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`. + +[id="api-updating-a-lifecycle-environment"] +.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 '{"description":"Quality Acceptance Testing"}' \ +https://_{foreman-example-com}_/katello/api/environments/3 \ +| python3 -m json.tool +---- + +.API 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_ +---- diff --git a/guides/common/modules/proc_uploading-content-larger-than-2-mib.adoc b/guides/common/modules/proc_uploading-content-larger-than-2-mib.adoc new file mode 100644 index 00000000000..50ccb72253d --- /dev/null +++ b/guides/common/modules/proc_uploading-content-larger-than-2-mib.adoc @@ -0,0 +1,169 @@ +[id="uploading-content-larger-than-2-mib"] += Uploading content larger than 2 MiB + +The following example demonstrates how to split a large file into chunks, create an upload request, upload the individual files, import them to {Project}, and then delete the upload request. +Note that this example uses sample content, host names, user names, repository ID, and file names. + +[id="api-uploading-content-larger-than-2-mib"] +.API procedure +. Assign the package name to the variable `name`: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ export name=bpftool-3.10.0-1160.2.1.el7.centos.plus.x86_64.rpm +---- +. Assign the checksum of the file to the variable `checksum`: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ export checksum=$(sha256sum $name|cut -c 1-65) +---- +. Assign the file size to the variable `size`: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ export size=$(du -bs $name|cut -f 1) +---- +. The following command creates a new upload request and returns the upload ID of the request by using `size` and `checksum`. ++ +Example request: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl \ +--header 'Content-Type: application/json' \ +--request POST \ +--user _My_User_Name_:__My_Password__ \ +--data "{\"size\": \"$size\", \"checksum\":\"$checksum\"}" \ +https://_{foreman-example-com}_/katello/api/v2/repositories/76/content_uploads +---- ++ +where 76, in this case, is an example Repository ID. ++ +Example output ++ +[source, none, options="nowrap", subs="+quotes,attributes"] +---- +{"upload_id":"37eb5900-597e-4ac3-9bc5-2250c302fdc4"} +---- +. Assign the upload ID to the variable `upload_id`: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ export upload_id=37eb5900-597e-4ac3-9bc5-2250c302fdc4 +---- +. Split the file in 2MB chunks: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ split \ +--bytes 2MB \ +--numeric-suffixes \ +--suffix-length=1 \ +bpftool-3.10.0-1160.2.1.el7.centos.plus.x86_64.rpm bpftool +---- ++ +View the file chunks: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ ls -l bpftool[0-9] +---- ++ +Example output: ++ +[source, none, options="nowrap", subs="+quotes,attributes"] +---- +-rw-r--r--. 1 root root 2000000 Mar 31 14:15 bpftool0 +-rw-r--r--. 1 root root 2000000 Mar 31 14:15 bpftool1 +-rw-r--r--. 1 root root 2000000 Mar 31 14:15 bpftool2 +-rw-r--r--. 1 root root 2000000 Mar 31 14:15 bpftool3 +-rw-r--r--. 1 root root 868648 Mar 31 14:15 bpftool4 +---- +. Assign the prefix of the split files to the variable path. ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ export path=/root/tmp/bpftool +---- +. Upload the file chunks. +The offset starts at 0 bytes for the first chunk and increases by 2000000 bytes 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. ++ +Example requests: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl \ +--user _My_User_Name_:__My_Password__ \ +--header Accept:application/json \ +--header Content-Type:multipart/form-data \ +--request PUT \ +--data-urlencode size=$size \ +--data-urlencode offset=0 \ +--data-urlencode content@$\{path}0 \ +https://_{foreman-example-com}_/katello/api/v2/repositories/76/content_uploads/$upload_id + +$ curl \ +--user _My_User_Name_:__My_Password__ \ +--header Accept:application/json \ +--header Content-Type:multipart/form-data \ +--request PUT \ +--data-urlencode size=$size \ +--data-urlencode offset=2000000 \ +--data-urlencode content@$\{path}1 \ +https://_{foreman-example-com}_/katello/api/v2/repositories/76/content_uploads/$upload_id + +$ curl \ +--user _My_User_Name_:__My_Password__ \ +--header Accept:application/json \ +--header Content-Type:multipart/form-data \ +--request PUT \ +--data-urlencode size=$size \ +--data-urlencode offset=4000000 \ +--data-urlencode content@$\{path}2 \ +https://_{foreman-example-com}_/katello/api/v2/repositories/76/content_uploads/$upload_id + +$ curl \ +--user _My_User_Name_:__My_Password__ \ +--header Accept:application/json \ +--header Content-Type:multipart/form-data \ +--request PUT \ +--data-urlencode size=$size \ +--data-urlencode offset=6000000 +--data-urlencode content@$\{path}3 \ +https://_{foreman-example-com}_/katello/api/v2/repositories/76/content_uploads/$upload_id + +$ curl \ +--user _My_User_Name_:__My_Password__ \ +--header Accept:application/json \ +--header Content-Type:multipart/form-data \ +--request PUT \ +--data-urlencode size=$size \ +--data-urlencode offset=8000000 \ +--data-urlencode content@$\{path}4 \ +https://_{foreman-example-com}_/katello/api/v2/repositories/76/content_uploads/$upload_id +---- +. Import the complete upload to the repository: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl \ +--header "Content-Type:application/json" \ +--request PUT \ +--user _My_User_Name_:__My_Password__ \ +--data "{\"uploads\":[{\"id\": \"$upload_id\", \"name\": \"$name\", \"checksum\": \"$checksum\" }]}" \ +https://_{foreman-example-com}_/katello/api/v2/repositories/76/import_uploads +---- +. Delete the upload request: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl \ +--header 'Content-Type: application/json' \ +--request DELETE \ +--user _My_User_Name_:__My_Password__ \ +--data "{}" \ +https://_{foreman-example-com}_/katello/api/v2/repositories/76/content_uploads/$upload_id +---- diff --git a/guides/common/modules/proc_uploading-content-to-projectserver.adoc b/guides/common/modules/proc_uploading-content-to-projectserver.adoc index 709eeb8daf8..9e9f5bc7ea6 100644 --- a/guides/common/modules/proc_uploading-content-to-projectserver.adoc +++ b/guides/common/modules/proc_uploading-content-to-projectserver.adoc @@ -118,211 +118,3 @@ $ curl \ --data "{}" \ https://_{foreman-example-com}_/katello/api/v2/repositories/76/content_uploads/$upload_id ---- - -[id="api-uploading-content-larger-than-2-mib"] -.Uploading content larger than 2 MiB - -The following example demonstrates how to split a large file into chunks, create an upload request, upload the individual files, import them to {Project}, and then delete the upload request. -Note that this example uses sample content, host names, user names, repository ID, and file names. - -. Assign the package name to the variable `name`: -+ -[options="nowrap", subs="+quotes,attributes"] ----- -$ export name=bpftool-3.10.0-1160.2.1.el7.centos.plus.x86_64.rpm ----- -. Assign the checksum of the file to the variable `checksum`: -+ -[options="nowrap", subs="+quotes,attributes"] ----- -$ export checksum=$(sha256sum $name|cut -c 1-65) ----- -. Assign the file size to the variable `size`: -+ -[options="nowrap", subs="+quotes,attributes"] ----- -$ export size=$(du -bs $name|cut -f 1) ----- -. The following command creates a new upload request and returns the upload ID of the request by using `size` and `checksum`. -+ -Example request: -+ -[options="nowrap", subs="+quotes,attributes"] ----- -$ curl \ ---header 'Content-Type: application/json' \ ---request POST \ ---user _My_User_Name_:__My_Password__ \ ---data "{\"size\": \"$size\", \"checksum\":\"$checksum\"}" \ -https://_{foreman-example-com}_/katello/api/v2/repositories/76/content_uploads ----- -+ -where 76, in this case, is an example Repository ID. -+ -Example output -+ -[source, none, options="nowrap", subs="+quotes,attributes"] ----- -{"upload_id":"37eb5900-597e-4ac3-9bc5-2250c302fdc4"} ----- -. Assign the upload ID to the variable `upload_id`: -+ -[options="nowrap", subs="+quotes,attributes"] ----- -$ export upload_id=37eb5900-597e-4ac3-9bc5-2250c302fdc4 ----- -. Split the file in 2MB chunks: -+ -[options="nowrap", subs="+quotes,attributes"] ----- -$ split \ ---bytes 2MB \ ---numeric-suffixes \ ---suffix-length=1 \ -bpftool-3.10.0-1160.2.1.el7.centos.plus.x86_64.rpm bpftool ----- -+ -View the file chunks: -+ -[options="nowrap", subs="+quotes,attributes"] ----- -$ ls -l bpftool[0-9] ----- -+ -Example output: -+ -[source, none, options="nowrap", subs="+quotes,attributes"] ----- --rw-r--r--. 1 root root 2000000 Mar 31 14:15 bpftool0 --rw-r--r--. 1 root root 2000000 Mar 31 14:15 bpftool1 --rw-r--r--. 1 root root 2000000 Mar 31 14:15 bpftool2 --rw-r--r--. 1 root root 2000000 Mar 31 14:15 bpftool3 --rw-r--r--. 1 root root 868648 Mar 31 14:15 bpftool4 ----- -. Assign the prefix of the split files to the variable path. -+ -[options="nowrap", subs="+quotes,attributes"] ----- -$ export path=/root/tmp/bpftool ----- -. Upload the file chunks. -The offset starts at 0 bytes for the first chunk and increases by 2000000 bytes 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. -+ -Example requests: -+ -[options="nowrap", subs="+quotes,attributes"] ----- -$ curl \ ---user _My_User_Name_:__My_Password__ \ ---header Accept:application/json \ ---header Content-Type:multipart/form-data \ ---request PUT \ ---data-urlencode size=$size \ ---data-urlencode offset=0 \ ---data-urlencode content@$\{path}0 \ -https://_{foreman-example-com}_/katello/api/v2/repositories/76/content_uploads/$upload_id - -$ curl \ ---user _My_User_Name_:__My_Password__ \ ---header Accept:application/json \ ---header Content-Type:multipart/form-data \ ---request PUT \ ---data-urlencode size=$size \ ---data-urlencode offset=2000000 \ ---data-urlencode content@$\{path}1 \ -https://_{foreman-example-com}_/katello/api/v2/repositories/76/content_uploads/$upload_id - -$ curl \ ---user _My_User_Name_:__My_Password__ \ ---header Accept:application/json \ ---header Content-Type:multipart/form-data \ ---request PUT \ ---data-urlencode size=$size \ ---data-urlencode offset=4000000 \ ---data-urlencode content@$\{path}2 \ -https://_{foreman-example-com}_/katello/api/v2/repositories/76/content_uploads/$upload_id - -$ curl \ ---user _My_User_Name_:__My_Password__ \ ---header Accept:application/json \ ---header Content-Type:multipart/form-data \ ---request PUT \ ---data-urlencode size=$size \ ---data-urlencode offset=6000000 ---data-urlencode content@$\{path}3 \ -https://_{foreman-example-com}_/katello/api/v2/repositories/76/content_uploads/$upload_id - -$ curl \ ---user _My_User_Name_:__My_Password__ \ ---header Accept:application/json \ ---header Content-Type:multipart/form-data \ ---request PUT \ ---data-urlencode size=$size \ ---data-urlencode offset=8000000 \ ---data-urlencode content@$\{path}4 \ -https://_{foreman-example-com}_/katello/api/v2/repositories/76/content_uploads/$upload_id ----- -. Import the complete upload to the repository: -+ -[options="nowrap", subs="+quotes,attributes"] ----- -$ curl \ ---header "Content-Type:application/json" \ ---request PUT \ ---user _My_User_Name_:__My_Password__ \ ---data "{\"uploads\":[{\"id\": \"$upload_id\", \"name\": \"$name\", \"checksum\": \"$checksum\" }]}" \ -https://_{foreman-example-com}_/katello/api/v2/repositories/76/import_uploads ----- -. Delete the upload request: -+ -[options="nowrap", subs="+quotes,attributes"] ----- -$ curl \ ---header 'Content-Type: application/json' \ ---request DELETE \ ---user _My_User_Name_:__My_Password__ \ ---data "{}" \ -https://_{foreman-example-com}_/katello/api/v2/repositories/76/content_uploads/$upload_id ----- - -[id="api-uploading-duplicate-content"] -.Uploading duplicate content - -Note that if you try to upload duplicate content using: - -Example request: - -[options="nowrap", subs="+quotes,attributes"] ----- -$ curl \ ---header 'Content-Type: application/json' \ ---request POST \ ---user _My_User_Name_:__My_Password__ \ ---data "{\"size\": \"$size\", \"checksum\":\"$checksum\"}" \ -https://_{foreman-example-com}_/katello/api/v2/repositories/76/content_uploads ----- - -The call will return a content unit ID instead of an upload ID, similar to this: - -[source, none, options="nowrap", subs="+quotes,attributes"] ----- -{"content_unit_href":"/pulp/api/v3/content/file/files/c1bcdfb8-d840-4604-845e-86e82454c747/"} ----- - -You can copy this output and call import uploads directly to add the content to a repository: - -Example request: - -[options="nowrap", subs="+quotes,attributes"] ----- -$ curl \ ---header "Content-Type:application/json" \ ---request PUT \ ---user _My_User_Name_:__My_Password__ \ ---data "{\"uploads\":[{\"content_unit_id\": \"/pulp/api/v3/content/file/files/c1bcdfb8-d840-4604-845e-86e82454c747/\", \"name\": \"$name\", \ \"checksum\": \"$checksum\" }]}" \ -https://_{foreman-example-com}_/katello/api/v2/repositories/76/import_uploads ----- - -Note that the call changes from using `upload_id` to using `content_unit_id`. diff --git a/guides/common/modules/proc_uploading-duplicate-content.adoc b/guides/common/modules/proc_uploading-duplicate-content.adoc new file mode 100644 index 00000000000..46dba366ca0 --- /dev/null +++ b/guides/common/modules/proc_uploading-duplicate-content.adoc @@ -0,0 +1,40 @@ +[id="uploading-duplicate-content"] += Uploading duplicate content + +You can reuse existing content in {Project} instead of uploading duplicate content to {Project} through the API. + +[id="api-uploading-duplicate-content"] +.API procedure +* Upload content to {Project}: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl \ +--header 'Content-Type: application/json' \ +--request POST \ +--user _My_User_Name_:__My_Password__ \ +--data "{\"size\": \"$size\", \"checksum\":\"$checksum\"}" \ +https://_{foreman-example-com}_/katello/api/v2/repositories/76/content_uploads +---- ++ +The call will return a content unit ID instead of an upload ID, similar to this: ++ +[source, none, options="nowrap", subs="+quotes,attributes"] +---- +{"content_unit_href":"/pulp/api/v3/content/file/files/c1bcdfb8-d840-4604-845e-86e82454c747/"} +---- ++ +You can copy this output and call import uploads directly to add the content to a repository: + +.API response +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl \ +--header "Content-Type:application/json" \ +--request PUT \ +--user _My_User_Name_:__My_Password__ \ +--data "{\"uploads\":[{\"content_unit_id\": \"/pulp/api/v3/content/file/files/c1bcdfb8-d840-4604-845e-86e82454c747/\", \"name\": \"$name\", \ \"checksum\": \"$checksum\" }]}" \ +https://_{foreman-example-com}_/katello/api/v2/repositories/76/import_uploads +---- ++ +Note that the call changes from using `upload_id` to using `content_unit_id`. diff --git a/guides/common/modules/proc_using-searches-with-pagination-control.adoc b/guides/common/modules/proc_using-searches-with-pagination-control.adoc index 6d905295ea0..b22c229a3f6 100644 --- a/guides/common/modules/proc_using-searches-with-pagination-control.adoc +++ b/guides/common/modules/proc_using-searches-with-pagination-control.adoc @@ -6,30 +6,11 @@ The `per_page` parameter specifies the number of results per page and the `page` The default number of items to return is set to 1000 when you do not specify any pagination parameters, but the `per_page` value has a default of 20 which applies when you specify the `page` parameter. -[id="listing-content-views"] -.Listing content views - -This example returns a list of Content Views in pages. -The list contains 10 keys per page and returns the third page. - -Example request: - -[options="nowrap", subs="+quotes,attributes"] ----- -$ curl \ ---request GET \ ---user _My_User_Name_:__My_Password__ \ -https://{foreman-example-com}/katello/api/content_views?per_page=10&page=3 ----- - -[id="listing-activation-keys"] -.Listing activation keys - This example returns a list of activation keys for an organization with ID `1` in pages. The list contains 30 keys per page and returns the second page. -Example request: - +[id="api-using-searches-with-pagination-control"] +.API request [options="nowrap", subs="+quotes,attributes"] ---- $ curl \ @@ -37,19 +18,3 @@ $ curl \ --user _My_User_Name_:__My_Password__ \ https://{foreman-example-com}/katello/api/activation_keys?organization_id=1&per_page=30&page=2 ---- - -[id="returning-multiple-pages"] -.Returning multiple pages - -You can use a `for` loop structure to get multiple pages of results. -This example returns pages 1 to 3 of Content Views with 5 results per page: - -[source, bash, options="nowrap", subs="+quotes,attributes"] ----- -$ for i in `seq 1 3`; do \ - curl \ - --request GET \ - --user _My_User_Name_:__My_Password__ \ - https://{foreman-example-com}/katello/api/content_views?per_page=5&page=$i; \ -done ----- diff --git a/guides/common/modules/proc_using-the-delete-http-method.adoc b/guides/common/modules/proc_using-the-delete-http-method.adoc index aae5053b60a..592b3a5314b 100644 --- a/guides/common/modules/proc_using-the-delete-http-method.adoc +++ b/guides/common/modules/proc_using-the-delete-http-method.adoc @@ -2,11 +2,10 @@ = Using the DELETE HTTP method To delete a resource, use the DELETE method with an API route that includes the ID of the resource you want to delete. +This example deletes the `TestKey` activation key which ID is 2. -.Example -This example deletes the `TestKey` activation key which ID is 2: - -Example request: +[id="api-using-the-delete-http-method"] +.API request [options="nowrap", subs="+quotes,attributes"] ---- $ curl \ @@ -18,7 +17,7 @@ https://_{foreman-example-com}_/katello/api/activation_keys/2 \ | python3 -m json.tool ---- -Example response: +.API response [source, none, options="nowrap", subs="+quotes,attributes"] ---- _output omitted_ diff --git a/guides/common/modules/proc_using-the-get-http-method.adoc b/guides/common/modules/proc_using-the-get-http-method.adoc index 553b6229eaa..d995aafde2f 100644 --- a/guides/common/modules/proc_using-the-get-http-method.adoc +++ b/guides/common/modules/proc_using-the-get-http-method.adoc @@ -2,9 +2,10 @@ = Using the GET HTTP method Use the GET HTTP method to get data from the API about an existing entry or resource. -This example requests the number of registered {Project} hosts. +This example requests the number of registered hosts. -.Example request +[id="api-using-the-get-http-method"] +.API request [options="nowrap", subs="+quotes,attributes"] ---- $ curl \ @@ -14,7 +15,7 @@ https://_{foreman-example-com}_/api/hosts \ | python3 -m json.tool ---- -.Example response +.API response [source, none, options="nowrap", subs="+quotes,attributes"] ---- { @@ -28,7 +29,8 @@ https://_{foreman-example-com}_/api/hosts \ "order": null }, "results": -_output truncated_ + _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. diff --git a/guides/common/modules/proc_using-the-post-http-method.adoc b/guides/common/modules/proc_using-the-post-http-method.adoc index 4069f794b59..592d0c929d7 100644 --- a/guides/common/modules/proc_using-the-post-http-method.adoc +++ b/guides/common/modules/proc_using-the-post-http-method.adoc @@ -5,15 +5,14 @@ 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:passing-json-data-to-the-api-request[]. -.Example to create an activation key - +[id="api-using-the-post-http-method"] +.API procedure . Create a test file, for example, `activation-key.json`, with the following content: + [source, none, options="nowrap", subs="+quotes,attributes"] ---- {"organization_id":1, "name":"TestKey", "description":"Just for testing"} ---- - . Create an activation key by applying the data in the `activation-key.json` file: + Example request: @@ -71,5 +70,5 @@ Example response: } ---- -. Verify that the new activation key is present. -In the {ProjectWebUI}, navigate to *Content* > *Lifecycle* > *Activation Keys* to view your activation keys. +.Verification +* In the {ProjectWebUI}, navigate to *Content* > *Lifecycle* > *Activation Keys* to view your activation keys. diff --git a/guides/common/modules/proc_using-the-put-http-method.adoc b/guides/common/modules/proc_using-the-put-http-method.adoc index 4b9ab87ee0c..91e289d282e 100644 --- a/guides/common/modules/proc_using-the-put-http-method.adoc +++ b/guides/common/modules/proc_using-the-put-http-method.adoc @@ -5,17 +5,16 @@ Use the PUT HTTP method to change an existing value or append to an existing res You must submit the data in JSON format. For more information, see xref:passing-json-data-to-the-api-request[]. -.Example - This example updates the `TestKey` activation key created in the previous example. +[id="api-using-the-put-http-method"] +.API procedure . Edit the `activation-key.json` file created previously as follows: + [source, none, options="nowrap", subs="+quotes,attributes"] ---- {"organization_id":1, "name":"TestKey", "description":"Just for testing","max_hosts":"10" } ---- - . Apply the changes in the JSON file: + Example request: @@ -72,5 +71,4 @@ Example response: } } ---- - . In the {ProjectWebUI}, verify the changes by navigating to *Content* > *Lifecycle* > *Activation Keys*. diff --git a/guides/common/modules/proc_working-with-hosts.adoc b/guides/common/modules/proc_working-with-hosts.adoc deleted file mode 100644 index 9f3f6a9712d..00000000000 --- a/guides/common/modules/proc_working-with-hosts.adoc +++ /dev/null @@ -1,226 +0,0 @@ -[id="working-with-hosts"] -= Working with hosts - -[id="api-listing-hosts"] -.Listing hosts - -This example returns a list of {Project} hosts. - -Example request: -[options="nowrap", subs="+quotes,attributes"] ----- -$ curl \ ---request GET \ ---user _My_User_Name_:__My_Password__ \ -https://_{foreman-example-com}_/api/v2/hosts \ -| python3 -m json.tool ----- - -Example response: -[source, none, options="nowrap", subs="+quotes,attributes"] ----- -{ - ... - "total" => 2, - "subtotal" => 2, - "page" => 1, - "per_page" => 1000, - "search" => nil, - "sort" => { - "by" => nil, - "order" => nil - }, - "results" => [ - ... -} ----- - -[id="api-requesting-information-for-a-host"] -.Requesting information for a host - -This request returns information for the host `{foreman-example-com}`. - -Example request: -[options="nowrap", subs="+quotes,attributes"] ----- -$ curl \ ---request GET \ ---user _My_User_Name_:__My_Password__ \ -https://_{foreman-example-com}_/api/v2/hosts/_{foreman-example-com}_ \ -| python3 -m json.tool ----- - -Example response: -[source, none, options="nowrap", subs="+quotes,attributes"] ----- -{ - "all_puppetclasses": [], - "architecture_id": 1, - "architecture_name": "x86_64", - "build": false, - "capabilities": [ - "build" - ], - "certname": "_{foreman-example-com}_", - "comment": null, - "compute_profile_id": null, - ... -} ----- - -[id="api-listing-host-facts"] -.Listing host facts - -This request returns all facts for the host `{foreman-example-com}`. - -Example request: -[options="nowrap", subs="+quotes,attributes"] ----- -$ curl \ ---request GET \ ---user _My_User_Name_:__My_Password__ \ -https://_{foreman-example-com}_/api/v2/hosts/_{foreman-example-com}_/facts \ -| python3 -m json.tool ----- - -Example response: -[source, none, options="nowrap", subs="+quotes,attributes"] ----- -{ - ... - "results": { - "_{foreman-example-com}_": { - "augeasversion": "1.0.0", - "bios_release_date": "01/01/2007", - "bios_version": "0.5.1", - "blockdevice_sr0_size": "1073741312", - "facterversion": "1.7.6", - ... -} ----- - -[id="api-searching-for-hosts-with-matching-patterns"] -.Searching for hosts with matching patterns - -This query returns all hosts that match the pattern "example". - -Example request: -[options="nowrap", subs="+quotes,attributes"] ----- -$ curl \ ---request GET \ ---user _My_User_Name_:__My_Password__ \ -https://_{foreman-example-com}_/api/v2/hosts?search=example \ -| python3 -m json.tool ----- - -Example response: -[source, none, options="nowrap", subs="+quotes,attributes"] ----- -{ - ... - "results": [ - { - "name": "_{foreman-example-com}_", - ... - } - ], - "search": "example", - ... -} ----- - -[id="api-searching-for-hosts-in-an-environment"] -.Searching for hosts in an environment - -This query returns all hosts in the `production` environment. - -Example request: -[options="nowrap", subs="+quotes,attributes"] ----- -$ curl \ ---request GET \ ---user _My_User_Name_:__My_Password__ \ -https://_{foreman-example-com}_/api/v2/hosts?search=environment=production \ -| python3 -m json.tool ----- - -Example response: -[source, none, options="nowrap", subs="+quotes,attributes"] ----- -{ - ... - "results": [ - { - "environment_name": "production", - "name": "_{foreman-example-com}_", - ... - } - ], - "search": "environment=production", - ... -} ----- - -[id="api-searching-for-hosts-with-a-specific-fact-value"] -.Searching for hosts with a specific fact value - -This query returns all hosts with a model name `RHV Hypervisor`. - -Example request: -[options="nowrap", subs="+quotes,attributes"] ----- -$ curl \ ---request GET \ ---user _My_User_Name_:__My_Password__ \ -https://_{foreman-example-com}_/api/v2/hosts?search=model=\"RHV+Hypervisor\" \ -| python3 -m json.tool ----- - -Example response: -[source, none, options="nowrap", subs="+quotes,attributes"] ----- -{ - ... - "results": [ - { - "model_id": 1, - "model_name": "RHV Hypervisor", - "name": "_{foreman-example-com}_", - ... - } - ], - "search": "model=\"RHV Hypervisor\"", - ... -} ----- - -[id="api-deleting-a-host"] -.Deleting a host - -This request deletes a host with a name _host1.example.com_. - -Example 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 ----- - -[id="api-downloading-a-full-host-boot-disk-image"] -.Downloading a full-host boot disk image - -This request downloads a full boot disk image for a host by its ID. - -Example request: -[options="nowrap", subs="+quotes,attributes"] ----- -$ curl \ ---request GET \ ---user _My_User_Name_:__My_Password__ \ ---output _My_Image_.iso \ -https://_{foreman-example-com}_/api/bootdisk/hosts/_host_ID_?full=true ----- diff --git a/guides/common/modules/ref_json-response-format-for-collections.adoc b/guides/common/modules/ref_json-response-format-for-collections.adoc new file mode 100644 index 00000000000..abe99386e27 --- /dev/null +++ b/guides/common/modules/ref_json-response-format-for-collections.adoc @@ -0,0 +1,60 @@ +[id="json-response-format-for-collections"] += JSON response format for collections + +Collections are a list of objects such as hosts and domains. +The format for a collection JSON response consists of a metadata fields section and a results section. + +This is an example of the format for a collection request for a list of {Project} domains: + +[id="api-json-response-format-for-collections"] +.API request +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl \ +--request GET \ +--user _My_User_Name_:__My_Password__ \ +https://_{foreman-example-com}_/api/domains \ +| python3 -m json.tool +---- + +.API response +[source, none, options="nowrap", subs="+quotes,attributes"] +---- +{ + "total": 3, + "subtotal": 3, + "page": 1, + "per_page": 20, + "search": null, + "sort": { + "by": null, + "order": null + }, + "results": [ + { + "id": 23, + "name": "qa.lab.example.com", + "fullname": "QA", + "dns_id": 10, + "created_at": "2024-08-13T09:02:31Z", + "updated_at": "2024-08-13T09:02:31Z" + }, + { + "id": 25, + "name": "dev.lab.example.com", + "fullname": "DEVEL", + "dns_id": 8, + "created_at": "2024-08-13T08:32:48Z", + "updated_at": "2024-08-14T07:04:03Z" + }, + { + "id": 32, + "name": "hr.lab.example.com", + "fullname": "HR", + "dns_id": 8, + "created_at": "2024-08-16T08:32:48Z", + "updated_at": "2024-08-16T07:04:03Z" + } + ] +} +---- diff --git a/guides/common/modules/ref_json-response-format-for-single-objects.adoc b/guides/common/modules/ref_json-response-format-for-single-objects.adoc new file mode 100644 index 00000000000..9510c33a437 --- /dev/null +++ b/guides/common/modules/ref_json-response-format-for-single-objects.adoc @@ -0,0 +1,31 @@ +[id="json-response-format-for-single-objects"] += JSON response format for single objects + +You can use single-object JSON responses to work with a single object. +API requests to a single object require the unique identifier `:id` of the object. + +This is an example of the format for a single-object request for the {Project} domain which ID is 23: + +[id="api-json-response-format-for-single-objects"] +.API request +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl \ +--request GET \ +--user _My_User_Name_:__My_Password__ \ +https://_{foreman-example-com}_/api/domains/23 \ +| python3 -m json.tool +---- + +.API response +[options="nowrap", subs="+quotes,attributes"] +---- +{ + "id": 23, + "name": "qa.lab.example.com", + "fullname": "QA", + "dns_id": 10, + "created_at": "2024-08-13T09:02:31Z", + "updated_at": "2024-08-13T09:02:31Z" +} +---- diff --git a/guides/common/modules/ref_json-response-format.adoc b/guides/common/modules/ref_json-response-format.adoc deleted file mode 100644 index 55cf5b8b0c9..00000000000 --- a/guides/common/modules/ref_json-response-format.adoc +++ /dev/null @@ -1,110 +0,0 @@ -[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. - -.JSON response format for single objects - -You can use single-object JSON responses to work with a single object. -API requests to a single object require the unique identifier `:id` of the object. - -This is an example of the format for a single-object request for the {Project} domain which ID is 23: - -Example request: -[options="nowrap", subs="+quotes,attributes"] ----- -$ curl \ ---request GET \ ---user _My_User_Name_:__My_Password__ \ -https://_{foreman-example-com}_/api/domains/23 \ -| python3 -m json.tool ----- - -Example response: -[options="nowrap", subs="+quotes,attributes"] ----- -{ - "id": 23, - "name": "qa.lab.example.com", - "fullname": "QA", - "dns_id": 10, - "created_at": "2024-08-13T09:02:31Z", - "updated_at": "2024-08-13T09:02:31Z" -} ----- - -.JSON response format for collections - -Collections are a list of objects such as hosts and domains. -The format for a collection JSON response consists of a metadata fields section and a results section. - -This is an example of the format for a collection request for a list of {Project} domains: - -Example request: -[options="nowrap", subs="+quotes,attributes"] ----- -$ curl \ ---request GET \ ---user _My_User_Name_:__My_Password__ \ -https://_{foreman-example-com}_/api/domains \ -| python3 -m json.tool ----- - -Example response: -[source, none, options="nowrap", subs="+quotes,attributes"] ----- -{ - "total": 3, - "subtotal": 3, - "page": 1, - "per_page": 20, - "search": null, - "sort": { - "by": null, - "order": null - }, - "results": [ - { - "id": 23, - "name": "qa.lab.example.com", - "fullname": "QA", - "dns_id": 10, - "created_at": "2024-08-13T09:02:31Z", - "updated_at": "2024-08-13T09:02:31Z" - }, - { - "id": 25, - "name": "dev.lab.example.com", - "fullname": "DEVEL", - "dns_id": 8, - "created_at": "2024-08-13T08:32:48Z", - "updated_at": "2024-08-14T07:04:03Z" - }, - { - "id": 32, - "name": "hr.lab.example.com", - "fullname": "HR", - "dns_id": 8, - "created_at": "2024-08-16T08:32:48Z", - "updated_at": "2024-08-16T07:04:03Z" - } - ] -} ----- - -.JSON response metadata -API response uses the following metadata fields: - -* `total` {endash} The total number of objects without any search parameters. -* `subtotal` {endash} The number of objects returned with the given search parameters. -If there is no search, then subtotal is equal to total. -* `page` {endash} The page number. -* `per_page` {endash} The maximum number of objects returned per page. -* `limit` {endash} The specified number of objects to return in a collection response. -* `offset` {endash} The number of objects skipped before returning a collection. -* `search` {endash} The search string based on `scoped_scoped` syntax. -* `sort` -** `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` {endash} The collection of objects. diff --git a/guides/common/modules/ref_json-response-metadata.adoc b/guides/common/modules/ref_json-response-metadata.adoc new file mode 100644 index 00000000000..bb73bc14173 --- /dev/null +++ b/guides/common/modules/ref_json-response-metadata.adoc @@ -0,0 +1,17 @@ +[id="json-response-metadata"] += JSON response metadata + +{Project} API responses contain the following metadata fields: + +* `total` {endash} The total number of objects without any search parameters. +* `subtotal` {endash} The number of objects returned with the given search parameters. +If there is no search, then subtotal is equal to total. +* `page` {endash} The page number. +* `per_page` {endash} The maximum number of objects returned per page. +* `limit` {endash} The specified number of objects to return in a collection response. +* `offset` {endash} The number of objects skipped before returning a collection. +* `search` {endash} The search string based on `scoped_scoped` syntax. +* `sort` +** `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` {endash} The collection of objects. diff --git a/guides/common/modules/ref_oauth-request-format.adoc b/guides/common/modules/ref_oauth-request-format.adoc index 90618077bdd..bad27c7f42e 100644 --- a/guides/common/modules/ref_oauth-request-format.adoc +++ b/guides/common/modules/ref_oauth-request-format.adoc @@ -17,13 +17,13 @@ For an example that uses the *requests_oauthlib* Python module, see https://acce ==== endif::[] -.Example This example lists architectures by using OAuth for authentication. The request uses a _My_User_Name_ username in the `FOREMAN-USER` header. With the `--foreman-oauth-map-users` set to `true`, the response includes only architectures that the user has access to view. The signature reflects every parameter, HTTP method, and URI change. -Example request: +[id="api-oauth-request-format"] +.API request [options="nowrap", subs="+quotes,attributes"] ---- $ curl \