diff --git a/guides/common/assembly_api-call-authentication.adoc b/guides/common/assembly_api-call-authentication.adoc new file mode 100644 index 00000000000..f108c7ecd7b --- /dev/null +++ b/guides/common/assembly_api-call-authentication.adoc @@ -0,0 +1,19 @@ +include::modules/con_api-call-authentication.adoc[] + +include::modules/con_ssl-authentication-overview.adoc[leveloffset=+1] + +include::modules/proc_configuring-ssl-authentication.adoc[leveloffset=+2] + +include::modules/con_http-authentication-overview.adoc[leveloffset=+1] + +include::modules/con_token-authentication-overview.adoc[leveloffset=+1] + +include::modules/proc_creating-a-personal-access-token.adoc[leveloffset=+2] + +include::modules/proc_revoking-a-personal-access-token.adoc[leveloffset=+2] + +include::modules/con_oauth-authentication-overview.adoc[leveloffset=+1] + +include::modules/proc_configuring-oauth.adoc[leveloffset=+2] + +include::modules/ref_oauth-request-format.adoc[leveloffset=+2] diff --git a/guides/common/assembly_api-cheat-sheet.adoc b/guides/common/assembly_api-cheat-sheet.adoc new file mode 100644 index 00000000000..5ed140294e4 --- /dev/null +++ b/guides/common/assembly_api-cheat-sheet.adoc @@ -0,0 +1,19 @@ +include::modules/con_api-cheat-sheet.adoc[] + +include::modules/proc_working-with-hosts.adoc[leveloffset=+1] + +include::modules/proc_working-with-lifecycle-environments.adoc[leveloffset=+1] + +include::modules/proc_uploading-content-to-projectserver.adoc[leveloffset=+1] + +include::modules/proc_applying-errata-to-hosts.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_overriding-smart-class-parameters.adoc[leveloffset=+1] + +include::modules/proc_modifying-a-smart-class-parameter-by-using-an-external-file.adoc[leveloffset=+1] + +include::modules/proc_deleting-openscap-reports.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 new file mode 100644 index 00000000000..30049aad9f2 --- /dev/null +++ b/guides/common/assembly_api-requests-in-various-languages.adoc @@ -0,0 +1,7 @@ +include::modules/con_api-requests-in-various-languages.adoc[] + +include::modules/proc_calling-the-api-in-curl.adoc[leveloffset=+1] + +include::modules/proc_calling-the-api-in-ruby.adoc[leveloffset=+1] + +include::modules/proc_calling-the-api-in-python.adoc[leveloffset=+1] diff --git a/guides/common/assembly_api-syntax.adoc b/guides/common/assembly_api-syntax.adoc new file mode 100644 index 00000000000..68411d17459 --- /dev/null +++ b/guides/common/assembly_api-syntax.adoc @@ -0,0 +1,15 @@ +include::modules/con_api-syntax.adoc[] + +include::modules/con_api-request-composition.adoc[leveloffset=+1] + +include::modules/proc_using-the-get-http-method.adoc[leveloffset=+2] + +include::modules/proc_using-the-post-http-method.adoc[leveloffset=+2] + +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/ref_relating-api-error-messages-to-the-api-reference.adoc[leveloffset=+1] diff --git a/guides/common/assembly_introduction-to-project-api.adoc b/guides/common/assembly_introduction-to-project-api.adoc new file mode 100644 index 00000000000..fd83d091b0f --- /dev/null +++ b/guides/common/assembly_introduction-to-project-api.adoc @@ -0,0 +1,5 @@ +include::modules/con_introduction-to-project-api.adoc[] + +include::modules/con_overview-of-the-project-api.adoc[leveloffset=+1] + +include::modules/con_project-api-compared-to-hammer-cli.adoc[leveloffset=+1] diff --git a/guides/common/attributes-base.adoc b/guides/common/attributes-base.adoc index 1bda2f73f06..bba3d5431f5 100644 --- a/guides/common/attributes-base.adoc +++ b/guides/common/attributes-base.adoc @@ -1,6 +1,7 @@ // URLs :BaseFilenameURL: index-{build}.html :AdministeringDocURL: {BaseURL}Administering_Project/{BaseFilenameURL}# +:APIDocURL: {BaseURL}Project_API/{BaseFilenameURL}# :ConfiguringLoadBalancerDocURL: {BaseURL}Configuring_Load_Balancer/{BaseFilenameURL}# :ContentManagementDocURL: {BaseURL}Managing_Content/{BaseFilenameURL}# :HammerDocURL: {BaseURL}Hammer_CLI/{BaseFilenameURL}# @@ -111,6 +112,7 @@ :postgresql-conf-dir: {postgresql-data-dir} :postgresql-log-dir: {postgresql-data-dir}/log :PIV: PIV +:project-allcaps: FOREMAN :project-client-url: https://yum.theforeman.org/client/{ProjectVersion} :project-client-name: {project-client-url}[Foreman Client] :project-client-RHEL7-url: {project-client-url}/el7/x86_64/foreman-client-release.rpm diff --git a/guides/common/attributes-orcharhino.adoc b/guides/common/attributes-orcharhino.adoc index d43b64f9d48..955184d24da 100644 --- a/guides/common/attributes-orcharhino.adoc +++ b/guides/common/attributes-orcharhino.adoc @@ -4,6 +4,7 @@ :ProjectVersion: 6.10 :ProjectVersionPrevious: 6.9 :Project: orcharhino +:project-allcaps: ORCHARHINO :project-context: {Project} :ProjectFeed: https://orcharhino.com/feed/ :ProjectName: {Project} diff --git a/guides/common/attributes-satellite.adoc b/guides/common/attributes-satellite.adoc index 369326f2011..cb8e5c752a3 100644 --- a/guides/common/attributes-satellite.adoc +++ b/guides/common/attributes-satellite.adoc @@ -13,6 +13,7 @@ // - lib/foreman_theme_satellite/documentation.rb in RedHatSatellite/foreman_theme_satellite // - downstream_filename_to_link.json in downstream :AdministeringDocURL: {BaseURL}administering_red_hat_satellite/index# +:APIDocURL: {BaseURL}using_the_satellite_rest_api/index# :ConfiguringLoadBalancerDocURL: {BaseURL}configuring_capsules_with_a_load_balancer/index# :ContentManagementDocURL: {BaseURL}managing_content/index# :InstallingServerDisconnectedDocURL: {BaseURL}installing_satellite_server_in_a_disconnected_network_environment/index# @@ -35,7 +36,6 @@ // Not upstreamed :ReleaseNotesDocURL: {BaseURL}release_notes/index# -:APIDocURL: {BaseURL}api_guide/index# :ConfiguringVMSubscriptionsDocURL: {BaseURL}configuring_virtual_machine_subscriptions/index# :ConversionsToolkitDocURL: {BaseURL}converting_hosts_to_rhel_by_using_satellite_conversions_toolkit/index# @@ -101,6 +101,7 @@ :project-package-remove: satellite-maintain packages remove :project-package-update: satellite-maintain packages update :PIV: CAC +:project-allcaps: SATELLITE :project-context: satellite :project-change-hostname: satellite-change-hostname :project-minimum-memory: 20 GB diff --git a/guides/common/attributes-titles.adoc b/guides/common/attributes-titles.adoc index 324482ed058..a8e4ec94bf9 100644 --- a/guides/common/attributes-titles.adoc +++ b/guides/common/attributes-titles.adoc @@ -2,6 +2,7 @@ :AdministeringDocTitle: Administering {ProjectName} :AdministeringAnsibleDocTitle: Managing {Project} with Ansible +:APIDocTitle: Using the {Project} REST API :AppCentricDeploymentDocTitle: Deploying hosts by using application centric approach :ConfiguringLoadBalancerDocTitle: Configuring {SmartProxies} with a load balancer :ContentManagementDocTitle: Managing content @@ -32,7 +33,6 @@ :UpgradingDisconnectedPreviousDocTitle: Upgrading disconnected {ProjectName} to {ProjectVersionPrevious} // Not upstreamed -:APIDocTitle: API guide :ConfiguringVMSubscriptionsDocTitle: Configuring virtual machine subscriptions :ConversionsToolkitDocTitle: Converting hosts to RHEL by using Satellite conversions toolkit diff --git a/guides/common/modules/con_api-call-authentication.adoc b/guides/common/modules/con_api-call-authentication.adoc new file mode 100644 index 00000000000..bd270441ca4 --- /dev/null +++ b/guides/common/modules/con_api-call-authentication.adoc @@ -0,0 +1,5 @@ +[id="api-call-authentication"] += API call authentication + +Interaction with the {Project} API requires SSL authentication with {ProjectServer} CA certificate and authentication with valid {Project} user credentials. +You can use the following authentication methods. diff --git a/guides/common/modules/con_api-cheat-sheet.adoc b/guides/common/modules/con_api-cheat-sheet.adoc new file mode 100644 index 00000000000..ef94f5bdc95 --- /dev/null +++ b/guides/common/modules/con_api-cheat-sheet.adoc @@ -0,0 +1,37 @@ +[id="api-cheat-sheet"] += API cheat sheet + +You can review the following examples of how to use the {ProjectName} API to perform various tasks. +You can use the API on {ProjectServer} via HTTPS on port 443 or on {SmartProxyServer} via HTTPS on port 8443. + +[IMPORTANT] +==== +ifdef::foreman,katello[] +Calling the API through {SmartProxyServer} has been deprecated since {Project} 3.12. +endif::[] +ifdef::satellite[] +Calling the API through {SmartProxyServer} has been deprecated since {Project} 6.16. +endif::[] +ifdef::orcharhino[] +Calling the API through {SmartProxyServer} has been deprecated since {Project} XXX. +endif::[] +Migrate your integrations to call the API through {ProjectServer}. +==== + +You can address these different port requirements within the script itself. +For example, in Ruby, you can specify the {ProjectServer} and {SmartProxyServer} URLs as follows: + +[options="nowrap", subs="+quotes,verbatim,attributes"] +---- +url = 'https://_{foreman-example-com}_/api/v2/' +{smart-proxy-context}_url = 'https://_{smartproxy-example-com}_:8443/api/v2/' +ifdef::katello,orcharhino,satellite[] +katello_url = 'https://_{foreman-example-com}_/katello/api/v2/' +endif::[] +---- + +For the host that is registered to {ProjectServer} or {SmartProxyServer}, you can determine the correct port required to access the API from the `/etc/rhsm/rhsm.conf` file, in the port entry of the `[server]` section. +You can use these values to fully automate your scripts, removing any need to verify which ports to use. + +The following examples use `curl` for sending API requests. +For more information, see xref:calling-the-api-in-curl[]. diff --git a/guides/common/modules/con_api-request-composition.adoc b/guides/common/modules/con_api-request-composition.adoc new file mode 100644 index 00000000000..7a94db4bbde --- /dev/null +++ b/guides/common/modules/con_api-request-composition.adoc @@ -0,0 +1,39 @@ +[id="api-request-composition"] += API request composition + +The built-in API reference shows the API route, or path, preceded by an HTTP method: + +---- +HTTP_METHOD API_ROUTE +---- + +To work with the API, construct a command by using the `curl` command syntax and the API route from the reference document: + +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl --request _HTTP_METHOD_ \ #<1> +--insecure \ #<2> +--user _My_User_Name_:__My_Password__ \ #<3> +--data @_input_file_.json \ #<4> +--header "Accept:application/json" \ #<5> +--header "Content-Type:application/json" \ #<5> +--output _output_file_ #<6> +_API_ROUTE_ \ #<7> +| python3 -m json.tool #<8> +---- + +<1> To use `curl` for the API call, specify an HTTP method with the `--request` option. +For example, `--request POST`. +<2> Add the `--insecure` option to skip SSL peer certificate verification check. +{Team} recommends you to configure SSL authentication and use secured calls. +For more information, see xref:ssl-authentication-overview[]. +<3> Provide {Project} user credentials with the `--user` option. +<4> For `POST` and `PUT` requests, use the `--data` option to pass JSON-formatted data. +For more information, see xref:sect-API_Guide-Passing_JSON_Data_with_the_API_Request[]. +<5> When passing the JSON data with the `--data` option, you must specify the following headers with the `--header` option. +For more information, see xref:sect-API_Guide-Passing_JSON_Data_with_the_API_Request[]. +<6> When downloading content from {ProjectServer}, specify the output file with the `--output` option. +<7> Use the API route in the following format: `https://_{foreman-example-com}_/katello/api/activation_keys`. +In {ProjectX}, version 2 of the API is the default. +Therefore, it is not necessary to use `v2` in the URL for API calls. +<8> Redirect the output to the Python `json.tool` module to make the output easier to read. diff --git a/guides/common/modules/con_api-requests-in-various-languages.adoc b/guides/common/modules/con_api-requests-in-various-languages.adoc new file mode 100644 index 00000000000..6985901cf81 --- /dev/null +++ b/guides/common/modules/con_api-requests-in-various-languages.adoc @@ -0,0 +1,4 @@ +[id="api-requests-in-various-languages"] += API requests in various languages + +You can review the following examples of sending API requests to {ProjectName} from curl, Ruby, or Python. diff --git a/guides/common/modules/con_api-syntax.adoc b/guides/common/modules/con_api-syntax.adoc new file mode 100644 index 00000000000..345d94353ac --- /dev/null +++ b/guides/common/modules/con_api-syntax.adoc @@ -0,0 +1,9 @@ +[id="api-syntax"] += API syntax + +You can review the basic syntax of API requests and JSON responses. + +[IMPORTANT] +==== +Even though versions 1 and 2 of the {ProjectX} API are available, {Team} only supports version 2. +==== diff --git a/guides/common/modules/con_http-authentication-overview.adoc b/guides/common/modules/con_http-authentication-overview.adoc new file mode 100644 index 00000000000..de23e239d98 --- /dev/null +++ b/guides/common/modules/con_http-authentication-overview.adoc @@ -0,0 +1,17 @@ +[id="http-authentication-overview"] += HTTP authentication overview + +All requests to the {Project} API require a valid {Project} user name and password. +The API uses Basic HTTP authentication to encode these credentials and add to the `Authorization` header. +For more information about Basic authentication, see http://tools.ietf.org/html/rfc2617[RFC 2617 HTTP Authentication: Basic and Digest Access Authentication]. +If a request does not include an appropriate `Authorization` header, the API returns a `401 Authorization Required` error. + +[IMPORTANT] +==== +Basic authentication involves potentially sensitive information, for example, it sends passwords as plain text. +The REST API requires HTTPS for transport-level encryption of plain text requests. +==== + +Some base64 libraries break encoded credentials into multiple lines and terminate each line with a newline character. +This invalidates the header and causes a faulty request. +The `Authorization` header requires the encoded credentials to be on a single line within the header. diff --git a/guides/common/modules/con_introduction-to-project-api.adoc b/guides/common/modules/con_introduction-to-project-api.adoc new file mode 100644 index 00000000000..333c789876d --- /dev/null +++ b/guides/common/modules/con_introduction-to-project-api.adoc @@ -0,0 +1,6 @@ +[id="introduction-to-{project-context}-api"] += Introduction to {Project} API + +{ProjectName} provides a Representational State Transfer (REST) API. +The API provides software developers and system administrators with control over their {ProjectName} environment outside of the standard web interface. +The REST API is useful for developers and administrators who aim to integrate the functionality of {ProjectName} with custom scripts or external applications that access the API over HTTP. diff --git a/guides/common/modules/con_oauth-authentication-overview.adoc b/guides/common/modules/con_oauth-authentication-overview.adoc new file mode 100644 index 00000000000..1ba3dd94c2a --- /dev/null +++ b/guides/common/modules/con_oauth-authentication-overview.adoc @@ -0,0 +1,15 @@ +[id="oauth-authentication-overview"] += OAuth authentication overview + +As an alternative to Basic authentication, you can use limited OAuth 1.0a authentication. +This is sometimes referred to as _1-legged OAuth_. + +To view OAuth settings, in the {ProjectWebUI}, navigate to *Administer* > *Settings* > *Authentication*. +The *OAuth consumer key* is the token to be used by all OAuth clients. + +{Project} stores OAuth settings in the `/etc/foreman/settings.yaml` file. +Use the `{foreman-installer}` script to configure these settings. + +[role="_additional-resources"] +.Additional resources +* https://oauth.net/core/1.0a/[OAuth Core 1.0 specification, Revision A] diff --git a/guides/common/modules/con_overview-of-the-project-api.adoc b/guides/common/modules/con_overview-of-the-project-api.adoc new file mode 100644 index 00000000000..6f8c4be347d --- /dev/null +++ b/guides/common/modules/con_overview-of-the-project-api.adoc @@ -0,0 +1,15 @@ +[id="overview-of-the-{project-context}-api_{context}"] += Overview of the {Project} API + +The benefits of using the REST API are: + +* Broad client support {endash} any programming language, framework, or system with support for HTTP protocol can use the API. +* Self-descriptive {endash} client applications require minimal knowledge of the {ProjectName} infrastructure because a user discovers many details at runtime. +* Resource-based model {endash} the resource-based REST model provides a natural way to manage a virtualization platform. + +You can use the REST API to perform the following tasks: + +* Integrate with enterprise IT systems. +* Integrate with third-party applications. +* Perform automated maintenance or error checking tasks. +* Automate repetitive tasks with scripts. diff --git a/guides/common/modules/con_project-api-compared-to-hammer-cli.adoc b/guides/common/modules/con_project-api-compared-to-hammer-cli.adoc new file mode 100644 index 00000000000..0f4c46bf219 --- /dev/null +++ b/guides/common/modules/con_project-api-compared-to-hammer-cli.adoc @@ -0,0 +1,9 @@ +[id="{project-context}-api-compared-to-hammer-cli_{context}"] += {Project} API compared to Hammer CLI + +For many tasks, you can use both Hammer and {Project} API. +You can use Hammer as a human-friendly interface to {Project} API. +For example, to test responses to API calls before applying them in a script, use the `--debug` option to inspect API calls that Hammer issues: `hammer --debug organization list`. +In contrast, scripts that use API commands communicate directly with the {Project} API. + +For more information, see the link:{HammerDocURL}[_{HammerDocTitle}_]. diff --git a/guides/common/modules/con_ssl-authentication-overview.adoc b/guides/common/modules/con_ssl-authentication-overview.adoc new file mode 100644 index 00000000000..c7514ea726f --- /dev/null +++ b/guides/common/modules/con_ssl-authentication-overview.adoc @@ -0,0 +1,14 @@ +[id="ssl-authentication-overview"] += SSL authentication overview + +{ProjectName} uses HTTPS, which provides a degree of encryption and identity verification when communicating with {ProjectServer}. +{Project} {ProjectVersion} does not support non-SSL communications. + +By default, {ProjectServer} uses a self-signed certificate. +This certificate acts as both the server certificate to verify the encryption key and the certificate authority (CA) to trust the identity of {ProjectServer}. + +You can configure {ProjectServer} to use a custom SSL certificate. +For more information, see {InstallingServerDocURL}Configuring_Server_with_a_Custom_SSL_Certificate_{project-context}[Configuring {ProjectServer} with a custom SSL certificate] in _{InstallingServerDocTitle}_. +ifdef::satellite[] +For more information on disconnected {ProjectServer}, see {InstallingServerDisconnectedDocURL}Configuring_Server_with_a_Custom_SSL_Certificate_{project-context}[Configuring {ProjectServer} with a custom SSL certificate] in _{InstallingServerDisconnectedDocTitle}_. +endif::[] diff --git a/guides/common/modules/con_token-authentication-overview.adoc b/guides/common/modules/con_token-authentication-overview.adoc new file mode 100644 index 00000000000..3cd4cef22ea --- /dev/null +++ b/guides/common/modules/con_token-authentication-overview.adoc @@ -0,0 +1,5 @@ +[id="token-authentication-overview"] += Token authentication overview + +{ProjectName} supports {PAT}s that you can use to authenticate API requests instead of using your password. +You can set an expiration date for your {PAT} and you can revoke it if you decide it should expire before the expiration date. diff --git a/guides/common/modules/proc_accessing-the-built-in-api-reference.adoc b/guides/common/modules/proc_accessing-the-built-in-api-reference.adoc new file mode 100644 index 00000000000..fb88537f79b --- /dev/null +++ b/guides/common/modules/proc_accessing-the-built-in-api-reference.adoc @@ -0,0 +1,14 @@ +[id="accessing-the-built-in-api-reference"] += Accessing the built-in API reference + +You can access the full API reference on your {ProjectServer}. + +.Procedure +* In your browser, access the following URL: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +https://_{foreman-example-com}_/apidoc/v2.html +---- ++ +Replace _{foreman-example-com}_ with the FQDN of your {ProjectServer}. diff --git a/guides/common/modules/proc_applying-errata-to-hosts.adoc b/guides/common/modules/proc_applying-errata-to-hosts.adoc new file mode 100644 index 00000000000..bfcfd7b4b52 --- /dev/null +++ b/guides/common/modules/proc_applying-errata-to-hosts.adoc @@ -0,0 +1,49 @@ +[id="applying-errata-to-hosts"] += Applying errata to hosts + +You can use the API to apply errata to a host, host group, or host collection. +The following is the basic syntax of a PUT request: + +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl --header "Accept:application/json" \ +--header "Content-Type:application/json" --request PUT \ +--user _My_User_Name_:__My_Password__ \ +--data _My_JSON_Formatted_Data_ https://_{foreman-example-com}_ +---- + +You can browse the built-in API doc to find a URL to use for applying errata. +You can use the {ProjectWebUI} to help discover the format for the search query. +Navigate to *Hosts* > *Host Collections* and select a host collection. +Go to *Collection Actions* > *Errata Installation* and notice the search query box contents. +For example, for a Host Collection called _my-collection_, the search box contains `host_collection="my-collection"`. + +[id="exam-API_Guide-Applying_Errata_to_a_Host"] +.Applying errata to a host + +This example uses the API URL for bulk actions `/katello/api/hosts/bulk/install_content` to show the format required for a simple search. + +Example request: +[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\":\"_my-host_\"},\"content_type\":\"errata\",\"content\":[\"_RHBA-2016:1981_\"]}" \ +https://_{foreman-example-com}_/api/v2/hosts/bulk/install_content +---- + +[id="exam-API_Guide-Applying_Errata_to_a_Host_Collection"] +.Applying errata to a host collection + +In this example, notice the level of escaping required to pass the search string `host_collection="my-collection"` as seen in the {ProjectWebUI}. +Example request: + +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl --header "Accept:application/json" \ +--header "Content-Type:application/json" --request PUT \ +--user _My_User_Name_:__My_Password__ \ +--data "{\"organization_id\":1,\"included\":{\"search\":\"host_collection=\\\"_my-collection_\\\"\"},\"content_type\":\"errata\",\"content\":[\"_RHBA-2016:1981_\"]}" \ +https://_{foreman-example-com}_/api/v2/hosts/bulk/install_content +---- diff --git a/guides/common/modules/proc_calling-the-api-in-curl.adoc b/guides/common/modules/proc_calling-the-api-in-curl.adoc new file mode 100644 index 00000000000..ae709c8da6f --- /dev/null +++ b/guides/common/modules/proc_calling-the-api-in-curl.adoc @@ -0,0 +1,198 @@ +[id="calling-the-api-in-curl"] += Calling the API in curl + +You can use `curl` with the {Project} API to perform various tasks. + +{ProjectName} requires the use of HTTPS, and by default a certificate for host identification. +If you have not added the {ProjectServer} certificate as described in xref:ssl-authentication-overview[], then you can use the `--insecure` option to bypass certificate checks. + +For user authentication, you can use the `--user` option to provide {Project} user credentials in the form `--user _username:password_` or, if you do not include the password, the command prompts you to enter it. +To reduce security risks, do not include the password as part of the command, because it then becomes part of your shell history. +Examples in this section include the password only for the sake of simplicity. + +Be aware that if you use the `--silent` option, `curl` does not display a progress meter or any error messages. + +Examples in this chapter use the Python `json.tool` module to format the output. + +[id="sect-API_Guide-Passing_JSON_Data_with_the_API_Request"] +== Passing JSON data to the API request + +You can pass data to {ProjectServer} with the API request. +The data must be in JSON format. +When specifying JSON data with the `--data` option, you must set the following HTTP headers with the `--header` option: + +---- +--header "Accept:application/json" \ +--header "Content-Type:application/json" +---- + +Use one of the following options to include data with the `--data` option. + +.JSON-formatted string +Enclose the quoted JSON-formatted data in curly braces `{}`. +When passing a value for a JSON type parameter, you must escape quotation marks `"` with backslashes `\`. +For example, within curly braces, you must format `"Example JSON Variable"` as `\"Example JSON Variable\"`: + +[options="nowrap", subs="+quotes,attributes"] +---- +--data {"id":44, "smart_class_parameter":{"override":"true", "parameter_type":"json", "default_value":"{\"GRUB_CMDLINE_LINUX\": {\"audit\":\"1\",\"crashkernel\":\"true\"}}"}} +---- + +.JSON-formatted file +The unquoted JSON-formatted data enclosed in a file and specified by the `@` sign and the filename. +For example: + +[options="nowrap", subs="+quotes,attributes"] +---- +--data @_file_.json +---- + +Using external files for JSON formatted data has the following advantages: + +* You can use your favorite text editor. +* You can use syntax checker to find and avoid mistakes. +* You can use tools to check the validity of JSON data or to reformat it. + +Use the `json_verify` tool to check the validity of the JSON file: + +[options="nowrap", subs="+quotes,attributes"] +---- +$ json_verify < _file_.json +---- + +[id="sect-API_Guide-Performing_Simple_Queries"] +== 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. + +.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: +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl --request GET --user _My_User_Name_:__My_Password__ \ +https://_{foreman-example-com}_/api/users | python3 -m json.tool +---- + +Example response: +[options="nowrap", subs="+quotes,attributes"] +---- +{ + "page": 1, + "per_page": 20, + "results": [ + { + "admin": false, + "auth_source_id": 1, + "auth_source_name": "Internal", + "created_at": "2018-09-21 08:59:22 UTC", + "default_location": null, + "default_organization": null, + "description": "", + "effective_admin": false, + "firstname": "", + "id": 5, + "last_login_on": "2018-09-21 09:03:25 UTC", + "lastname": "", + "locale": null, + "locations": [], + "login": "test", + "mail": "example@domain.com", + "organizations": [ + { + "id": 1, + "name": "Default Organization" + } + ], + "ssh_keys": [], + "timezone": null, + "updated_at": "2018-09-21 09:04:45 UTC" + }, + { + "admin": true, + "auth_source_id": 1, + "auth_source_name": "Internal", + "created_at": "2018-09-20 07:09:41 UTC", + "default_location": null, + "default_organization": { + "description": null, + "id": 1, + "name": "Default Organization", + "title": "Default Organization" + }, + "description": "", + "effective_admin": true, + "firstname": "Admin", + "id": 4, + "last_login_on": "2018-12-07 07:31:09 UTC", + "lastname": "User", + "locale": null, + "locations": [ + { + "id": 2, + "name": "Default Location" + } + ], + "login": "admin", + "mail": "root@example.com", + "organizations": [ + { + "id": 1, + "name": "Default Organization" + } + ], + "ssh_keys": [], + "timezone": null, + "updated_at": "2018-11-14 08:19:46 UTC" + } + ], + "search": null, + "sort": { + "by": null, + "order": null + }, + "subtotal": 2, + "total": 2 +} +---- + +[id="sect-API_Guide-Creating_and_Modifying_Resources"] +== Creating and modifying resources + +You can use `curl` to manipulate resources on your {ProjectServer}. +API calls to {Project} require data in `json` format. +For more information, see xref:sect-API_Guide-Passing_JSON_Data_with_the_API_Request[]. + +[id="ex-API_Guide-Creating_a_New_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 +---- + +.Modifying a user + +This example modifies given name and login of the `test_user` that was created in xref:ex-API_Guide-Creating_a_New_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_calling-the-api-in-python.adoc b/guides/common/modules/proc_calling-the-api-in-python.adoc new file mode 100644 index 00000000000..f2131c9a247 --- /dev/null +++ b/guides/common/modules/proc_calling-the-api-in-python.adoc @@ -0,0 +1,228 @@ +[id="calling-the-api-in-python"] += Calling the API in Python + +You can use Python with the {Project} API to perform various tasks. + +[IMPORTANT] +==== +These are example scripts and commands. +Ensure you review these scripts carefully before use, and replace any variables, user names, passwords, and other information to suit your own deployment. +==== + +Example scripts in this section do not use SSL verification for interacting with the REST API. + +[id="sect-API_Guide-Creating_Objects_Using_Python"] +== Creating objects by using Python + +This script connects to the {ProjectNameX} API and creates an organization, and then creates three environments in the organization. +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] +---- +#!/usr/bin/python3 + +import json +import sys + +try: + import requests +except ImportError: + print("Please install the python-requests module.") + sys.exit(-1) + +# URL to your {ProjectX} server +URL = "https://{foreman-example-com}" +# URL for the API to your deployed {ProjectX} server +{project_allcaps}_API = f"{URL}/katello/api/v2/" +# Katello-specific API +KATELLO_API = f"{URL}/katello/api/" +POST_HEADERS = {'content-type': 'application/json'} +# Default credentials to login to {ProjectX} +USERNAME = "admin" +PASSWORD = "changeme" +# Ignore SSL for now +SSL_VERIFY = False + +# Name of the organization to be either created or used +ORG_NAME = "MyOrg" +# Name for life cycle environments to be either created or used +ENVIRONMENTS = ["Development", "Testing", "Production"] + + +def get_json(location): + """ + Performs a GET by using the passed URL location + """ + r = requests.get(location, auth=(USERNAME, PASSWORD), verify=SSL_VERIFY) + return r.json() + + +def post_json(location, json_data): + """ + Performs a POST and passes the data to the URL location + """ + result = requests.post( + location, + data=json_data, + auth=(USERNAME, PASSWORD), + verify=SSL_VERIFY, + headers=POST_HEADERS + ) + return result.json() + + +def main(): + """ + Main routine that creates or re-uses an organization and + life cycle environments. + If life cycle environments already + exist, exit out. + """ + + # Check if our organization already exists + org = get_json(f"{project_allcaps}_API/organizations/{ORG_NAME}") + + # If our organization is not found, create it + if org.get('error', None): + org_id = post_json( + f"{project_allcaps}_API/organizations/", + json.dumps({"name": ORG_NAME}) + )["id"] + print("Creating organization:\t" + ORG_NAME) + else: + # Our organization exists, so let's grab it + org_id = org['id'] + print(f"Organization '{ORG_NAME}' exists.") + + # Now, let's fetch all available life cycle environments for this org... + envs = get_json( + f"{project_allcaps}_API/organizations/{org_id}/environments/" + ) + + # ...and add them to a dictionary, with respective 'Prior' environment + prior_env_id = 0 + env_list = {} + for env in envs['results']: + env_list[env['id']] = env['name'] + prior_env_id = env['id'] if env['name'] == "Library" else prior_env_id + + # Exit the script if at least one life cycle environment already exists + if all(environment in env_list.values() for environment in ENVIRONMENTS): + print("ERROR: One of the Environments is not unique to organization") + sys.exit(-1) + + # Create life cycle environments + for environment in ENVIRONMENTS: + new_env_id = post_json( + f"{project_allcaps}_API/organizations/{org_id}/environments/", + json.dumps({ + "name": environment, + "organization_id": org_id, + "prior": prior_env_id + }) + )["id"] + + print("Creating environment:\t" + environment) + prior_env_id = new_env_id + + +if __name__ == "__main__": + main() +---- + + +[id="sect-API_Guide-Requesting_information_from_the_API_using_Python"] +== Requesting information from the API by using Python + +This is an example script that uses Python for various API requests. + +.Python 3 example +[source, Python] +---- +#!/usr/bin/env python3 + +import json +import sys + +try: + import requests +except ImportError: + print("Please install the python-requests module.") + sys.exit(-1) + +SAT = "{foreman-example-com}" +# URL for the API to your deployed {ProjectX} server +{project-allcaps}_API = f"https://{SAT}/api/" +KATELLO_API = f"https://{SAT}/katello/api/v2/" + +POST_HEADERS = {'content-type': 'application/json'} +# Default credentials to login to {ProjectX} +USERNAME = "admin" +PASSWORD = "password" +# Ignore SSL for now +SSL_VERIFY = False +#SSL_VERIFY = "./path/to/CA-certificate.crt" # Put the path to your CA certificate here to allow SSL_VERIFY + + +def get_json(url): + # Performs a GET by using the passed URL location + r = requests.get(url, auth=(USERNAME, PASSWORD), verify=SSL_VERIFY) + return r.json() + +def get_results(url): + jsn = get_json(url) + if jsn.get('error'): + print("Error: " + jsn['error']['message']) + else: + if jsn.get('results'): + return jsn['results'] + elif 'results' not in jsn: + return jsn + else: + print("No results found") + return None + +def display_all_results(url): + results = get_results(url) + if results: + print(json.dumps(results, indent=4, sort_keys=True)) + +def display_info_for_hosts(url): + hosts = get_results(url) + if hosts: + print(f"{'ID':10}{'Name':40}{'IP':30}{'Operating System':30}") + for host in hosts: + print(f"{str(host['id']):10}{host['name']:40}{str(host['ip']):30}{str(host['operatingsystem_name']):30}") + +def display_info_for_subs(url): + subs = get_results(url) + if subs: + print(f"{'ID':10}{'Name':90}{'Start Date':30}") + for sub in subs: + print(f"{str(sub['id']):10}{sub['name']:90}{str(sub['start_date']):30}") + +def main(): + host = SAT + print(f"Displaying all info for host {host} ...") + display_all_results({project-allcaps}_API + 'hosts/' + host) + + print(f"Displaying all facts for host {host} ...") + display_all_results({project-allcaps}_API + f'hosts/{host}/facts') + + host_pattern = 'example' + print(f"Displaying basic info for hosts matching pattern '{host_pattern}'...") + display_info_for_hosts({project-allcaps}_API + 'hosts?per_page=1&search=name~' + host_pattern) + + print(f"Displaying basic info for subscriptions") + display_info_for_subs(KATELLO_API + 'subscriptions') + + environment = 'production' + print(f"Displaying basic info for hosts in environment {environment}...") + display_info_for_hosts({project-allcaps}_API + 'hosts?search=environment=' + environment) + + +if __name__ == "__main__": + main() +---- diff --git a/guides/common/modules/proc_calling-the-api-in-ruby.adoc b/guides/common/modules/proc_calling-the-api-in-ruby.adoc new file mode 100644 index 00000000000..d233080386d --- /dev/null +++ b/guides/common/modules/proc_calling-the-api-in-ruby.adoc @@ -0,0 +1,172 @@ +[id="calling-the-api-in-ruby"] += Calling the API in Ruby + +You can use Ruby with the {Project} API to perform various tasks. + +[IMPORTANT] +==== +These are example scripts and commands. +Ensure you review these scripts carefully before use, and replace any variables, user names, passwords, and other information to suit your own deployment. +==== + +[id="sect-API_Guide-Creating_Objects_Using_Ruby"] +== Creating objects by using Ruby + +This script connects to the {ProjectNameX} API and creates an organization, and then creates three lifecycle environments in the organization. +If the organization already exists, the script uses that organization. +If any of the lifecycle environments already exist in the organization, the script raises an error and quits. + +[source, Ruby] +---- +#!/usr/bin/ruby + +require 'rest-client' +require 'json' + +url = 'https://{foreman-example-com}/api/v2/' +katello_url = "#{url}/katello/api/v2/" + +$username = 'admin' +$password = 'changeme' + +org_name = "MyOrg" +environments = [ "Development", "Testing", "Production" ] + +# Performs a GET by using the passed URL location +def get_json(location) + response = RestClient::Request.new( + :method => :get, + :url => location, + :user => $username, + :password => $password, + :headers => { :accept => :json, + :content_type => :json } + ).execute + JSON.parse(response.to_str) +end + +# Performs a POST and passes the data to the URL location +def post_json(location, json_data) + response = RestClient::Request.new( + :method => :post, + :url => location, + :user => $username, + :password => $password, + :headers => { :accept => :json, + :content_type => :json}, + :payload => json_data + ).execute + JSON.parse(response.to_str) +end + +# Creates a hash with ids mapping to names for an array of records +def id_name_map(records) + records.inject({}) do |map, record| + map.update(record['id'] => record['name']) + end +end + +# Get list of existing organizations +orgs = get_json("#{katello_url}/organizations") +org_list = id_name_map(orgs['results']) + +if !org_list.has_value?(org_name) + # If our organization is not found, create it + puts "Creating organization: \t#{org_name}" + org_id = post_json("#{katello_url}/organizations", JSON.generate({"name"=> org_name}))["id"] +else + # Our organization exists, so let's grab it + org_id = org_list.key(org_name) + puts "Organization \"#{org_name}\" exists" +end + +# Get list of organization's lifecycle environments +envs = get_json("#{katello_url}/organizations/#{org_id}/environments") +env_list = id_name_map(envs['results']) +prior_env_id = env_list.key("Library") + +# Exit the script if at least one life cycle environment already exists +environments.each do |e| + if env_list.has_value?(e) + puts "ERROR: One of the Environments is not unique to organization" + exit + end +end + + # Create life cycle environments +environments.each do |environment| + puts "Creating environment: \t#{environment}" + prior_env_id = post_json("#{katello_url}/organizations/#{org_id}/environments", JSON.generate({"name" => environment, "organization_id" => org_id, "prior_id" => prior_env_id}))["id"] +end +---- + +[id="sect-API_Guide-API_Using_Apipie_Bindings"] +== Using apipie bindings with Ruby + +Apipie bindings are the Ruby bindings for apipie documented API calls. +They fetch and cache the API definition from {Project} and then generate API calls on demand. + +[source, Ruby] +---- +#!/usr/bin/ruby + +require 'apipie-bindings' + +org_name = "MyOrg" +environments = [ "Development", "Testing", "Production" ] + +# Create an instance of apipie bindings +@api = ApipieBindings::API.new({ + :uri => 'https://{foreman-example-com}/', + :username => 'admin', + :password => 'changeme', + :api_version => 2 +}) + +# Performs an API call with default options +def call_api(resource_name, action_name, params = {}) + http_headers = {} + apipie_options = { :skip_validation => true } + @api.resource(resource_name).call(action_name, params, http_headers, apipie_options) +end + +# Creates a hash with IDs mapping to names for an array of records +def id_name_map(records) + records.inject({}) do |map, record| + map.update(record['id'] => record['name']) + end +end + +# Get list of existing organizations +orgs = call_api(:organizations, :index) +org_list = id_name_map(orgs['results']) + +if !org_list.has_value?(org_name) + # If our organization is not found, create it + puts "Creating organization: \t#{org_name}" + org_id = call_api(:organizations, :create, {'organization' => { :name => org_name }})['id'] +else + # Our organization exists, so let's grab it + org_id = org_list.key(org_name) + puts "Organization \"#{org_name}\" exists" +end + +# Get list of organization's life cycle environments +envs = call_api(:lifecycle_environments, :index, {'organization_id' => org_id}) +env_list = id_name_map(envs['results']) +prior_env_id = env_list.key("Library") + +# Exit the script if at least one life cycle environment already exists +environments.each do |e| + if env_list.has_value?(e) + puts "ERROR: One of the Environments is not unique to organization" + exit + end +end + + # Create life cycle environments +environments.each do |environment| + puts "Creating environment: \t#{environment}" + prior_env_id = call_api(:lifecycle_environments, :create, {"name" => environment, "organization_id" => org_id, "prior_id" => prior_env_id })['id'] +end +---- diff --git a/guides/common/modules/proc_configuring-oauth.adoc b/guides/common/modules/proc_configuring-oauth.adoc new file mode 100644 index 00000000000..ae5273ac39b --- /dev/null +++ b/guides/common/modules/proc_configuring-oauth.adoc @@ -0,0 +1,29 @@ +[id="configuring-oauth"] += Configuring OAuth + +Use `{foreman-installer}` to change OAuth settings on {ProjectServer}. +Enter the following command to list all OAuth-related installer options: + +[options="nowrap", subs="+quotes,attributes"] +---- +# {foreman-installer} --full-help | grep oauth +---- + +.Enabling OAuth user mapping + +By default, {Project} authorizes all OAuth API requests as the built-in anonymous API administrator account. +Therefore, API responses include all {Project} data. +However, you can also specify the {Project} user that makes the request and restrict access to data to that user. + +To enable OAuth user mapping, enter the following command: + +[options="nowrap", subs="+quotes,attributes"] +---- +# {foreman-installer} --foreman-oauth-map-users true +---- + +[IMPORTANT] +==== +{Project} does not sign the header in an OAuth request. +Anyone with a valid consumer key can impersonate any {Project} user. +==== diff --git a/guides/common/modules/proc_configuring-ssl-authentication.adoc b/guides/common/modules/proc_configuring-ssl-authentication.adoc new file mode 100644 index 00000000000..4ce102c43a8 --- /dev/null +++ b/guides/common/modules/proc_configuring-ssl-authentication.adoc @@ -0,0 +1,42 @@ +[id="configuring-ssl-authentication"] += Configuring SSL authentication + +Configure an SSL authentication for the API requests to {ProjectServer}. + +.Procedure +. Obtain a certificate from your {ProjectServer} by using one of the following options: +* If you plan to call the API from a remote server, download the CA certificate: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +# curl -o /etc/pki/ca-trust/source/anchors/_{foreman-example-com}_-katello-server-ca.crt \ +http://{foreman-example-com}/pub/katello-server-ca.crt +---- +* If you plan to call the API directly on your {ProjectServer}, copy the certificate to the `/etc/pki/ca-trust/source/anchors` directory: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +# cp /var/www/html/pub/katello-server-ca.crt \ +/etc/pki/ca-trust/source/anchors/_{foreman-example-com}_-katello-server-ca.crt +---- +. Add the certificate to the list of trusted CAs: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +ifdef::foreman-deb[] +$ update-ca-certificates +endif::[] +ifndef::foreman-deb[] +$ update-ca-trust extract +endif::[] +---- + +.Verification +* Verify that your client trusts the {Project} SSL certificate by entering the API request without the `--cacert` option: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl --request GET \ +--user _My_User_Name_:__My_Password__ \ +https://_{foreman-example-com}_/api/v2/hosts +---- diff --git a/guides/common/modules/proc_deleting-openscap-reports.adoc b/guides/common/modules/proc_deleting-openscap-reports.adoc new file mode 100644 index 00000000000..ed46646e57e --- /dev/null +++ b/guides/common/modules/proc_deleting-openscap-reports.adoc @@ -0,0 +1,140 @@ +[id="deleting-openscap-reports"] += Deleting OpenSCAP reports + +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 +. List all OpenSCAP reports. +Note the IDs of the reports that you want to delete. ++ +Example request: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl --user _My_User_Name_:__My_Password__ \ +https://_{foreman-example-com}_/api/v2/compliance/arf_reports/ | python3 -m json.tool +---- ++ +Example response: ++ +[options="nowrap", subs="+quotes,attributes"] +---- + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed +100 3252 0 3252 0 0 4319 0 --:--:-- --:--:-- --:--:-- 4318 +{ + "page": 1, + "per_page": 20, + "results": [ + { + "created_at": "2017-05-16 13:27:09 UTC", + "failed": 0, + "host": "_host1.example.com_", + "id": 404, + "othered": 0, + "passed": 0, + "updated_at": "2017-05-16 13:27:09 UTC" + }, + { + "created_at": "2017-05-16 13:26:07 UTC", + "failed": 0, + "host": "_host2.example.com_, + "id": 405, + "othered": 0, + "passed": 0, + "updated_at": "2017-05-16 13:26:07 UTC" + }, + { + "created_at": "2017-05-16 13:25:07 UTC", + "failed": 0, + "host": "_host3.example.com_", + "id": 406, + "othered": 0, + "passed": 0, + "updated_at": "2017-05-16 13:25:07 UTC" + }, + { + "created_at": "2017-05-16 13:24:07 UTC", + "failed": 0, + "host": "_host4.example.com_", + "id": 407, + "othered": 0, + "passed": 0, + "updated_at": "2017-05-16 13:24:07 UTC" + }, + ], + "search": null, + "sort": { + "by": null, + "order": null + }, + "subtotal": 29, + "total": 29 +---- +. Using an ID from the previous step, delete the OpenSCAP report. +Repeat for each ID that you want to delete. ++ +Example request: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl --user _My_User_Name_:__My_Password__ \ +--header "Content-Type: application/json" \ +--request DELETE https://_{foreman-example-com}_/api/v2/compliance/arf_reports/405 +---- ++ +Example response: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +HTTP/1.1 200 OK +Date: Thu, 18 May 2017 07:14:36 GMT +Server: Apache/2.4.6 ({EL}) +X-Frame-Options: SAMEORIGIN +X-XSS-Protection: 1; mode=block +X-Content-Type-Options: nosniff +Foreman_version: 1.11.0.76 +Foreman_api_version: 2 +Apipie-Checksum: 2d39dc59aed19120d2359f7515e10d76 +Cache-Control: max-age=0, private, must-revalidate +X-Request-Id: f47eb877-35c7-41fe-b866-34274b56c506 +X-Runtime: 0.661831 +X-Powered-By: Phusion Passenger 4.0.18 +Set-Cookie: request_method=DELETE; path=/ +Set-Cookie: _session_id=d58fe2649e6788b87f46eabf8a461edd; path=/; secure; HttpOnly +ETag: "2574955fc0afc47cb5394ce95553f428" +Status: 200 OK +Vary: Accept-Encoding +Transfer-Encoding: chunked +Content-Type: application/json; charset=utf-8 +---- + +.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 + +#this script removes all the ARF reports from your {ProjectServer} + +#settings +USER=_username_ +PASS=_password_ +URI=https://_{foreman-example-com}_ + +#check amount of reports + while [ $(curl --user $USER:$PASS $URI/api/v2/compliance/arf_reports/ | python3 -m json.tool | grep \"\total\": | cut --fields=2 --delimiter":" | cut --fields=1 --delimiter"," | sed "s/ //g") -gt 0 ]; do + +#fetch reports + for i in $(curl --user $USER:$PASS $URI/api/v2/compliance/arf_reports/ | python3 -m json.tool | grep \"\id\": | cut --fields=2 --delimiter":" | cut --fields=1 --delimiter"," | sed "s/ //g") + +#delete reports + do + curl --user $USER:$PASS --header "Content-Type: application/json" --request DELETE $URI/api/v2/compliance/arf_reports/$i + done +done +---- diff --git a/guides/common/modules/proc_modifying-a-smart-class-parameter-by-using-an-external-file.adoc b/guides/common/modules/proc_modifying-a-smart-class-parameter-by-using-an-external-file.adoc new file mode 100644 index 00000000000..a6d5fe7c551 --- /dev/null +++ b/guides/common/modules/proc_modifying-a-smart-class-parameter-by-using-an-external-file.adoc @@ -0,0 +1,142 @@ +[id="modifying-a-smart-class-parameter-by-using-an-external-file"] += Modifying a Smart Class parameter by using an external file + +You can modify a Puppet Smart Class parameter by using an external file. + +Using external files simplifies working with JSON data. +You can use an editor with syntax highlighting to avoid and locate mistakes. + +[id="proc-API_Guide-Modifying_a_Smart_Class_Parameter_Using_an_External_File"] +.Modifying a Smart Class parameter by using an external file + +This example uses a MOTD Puppet manifest. + +. Search for the Puppet Class by name, `motd` in this case. ++ +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}_/api/smart_class_parameters?search=puppetclass_name=motd \ +| python3 -m json.tool +---- +. Examine the following output. +Each Smart Class Parameter has an ID that is global for the same {Project} instance. +The `content` parameter of the `motd` class has `id=3`. +Do not confuse this with the Puppet Class ID that displays before the Puppet Class name. ++ +Example response: ++ +[options="nowrap", subs="+quotes,verbatim,attributes"] +---- +{ + "avoid_duplicates": false, + *"created_at": "2017-02-06 12:37:48 UTC",* # Remove this line. + *"default_value": "",* # Add a new value here. + "description": "", + "hidden_value": "", + "hidden_value?": false, + "id": 3, + "merge_default": false, + "merge_overrides": false, + *"override": false,* # Set the override value to `true`. + "override_value_order": "fqdn\nhostgroup\nos\ndomain", + *"override_values": [],* # Remove this line. + "override_values_count": 0, + "parameter": "content", + "parameter_type": "string", + "puppetclass_id": 3, + "puppetclass_name": "motd", + "required": false, + *"updated_at": "2017-02-07 11:56:55 UTC",* # Remove this line. + "use_puppet_default": false, + "validator_rule": null, + "validator_type": "" +} +---- +. Use the parameter ID `3` to get the information specific to the `motd` parameter and redirect the output to a file, for example, *output_file.json*. ++ +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}_/api/smart_class_parameters/3 \ +| python3 -m json.tool > output_file.json +---- +. Copy the file created in the previous step to a new file for editing, for example, `changed_file.json`: ++ +---- +$ cp output_file.json changed_file.json +---- +. Modify the required values in the file. +In this example, change the content parameter of the `motd` module, which requires changing the `override` option from `false` to `true`: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +{ + "avoid_duplicates": false, + *"created_at": "2017-02-06 12:37:48 UTC",* # Remove this line. + *"default_value": "",* # Add a new value here. + "description": "", + "hidden_value": "", + "hidden_value?": false, + "id": 3, + "merge_default": false, + "merge_overrides": false, + *"override": false,* # Set the override value to `true`. + "override_value_order": "fqdn\nhostgroup\nos\ndomain", + *"override_values": [],* # Remove this line. + "override_values_count": 0, + "parameter": "content", + "parameter_type": "string", + "puppetclass_id": 3, + "puppetclass_name": "motd", + "required": false, + *"updated_at": "2017-02-07 11:56:55 UTC",* # Remove this line. + "use_puppet_default": false, + "validator_rule": null, + "validator_type": "" +} +---- +. After editing the file, verify that it looks as follows and then save the changes: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +{ + "avoid_duplicates": false, + *"default_value": "_No Unauthorized Access Allowed_",* + "description": "", + "hidden_value": "", + "hidden_value?": false, + "id": 3, + "merge_default": false, + "merge_overrides": false, + *"override": true,* + "override_value_order": "fqdn\nhostgroup\nos\ndomain", + "override_values_count": 0, + "parameter": "content", + "parameter_type": "string", + "puppetclass_id": 3, + "puppetclass_name": "motd", + "required": false, + "use_puppet_default": false, + "validator_rule": null, + "validator_type": "" +} +---- +. Submit the file to {Project}: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl --header "Accept:application/json" \ +--header "Content-Type:application/json" \ +--request PUT --user _My_User_Name_:__My_Password__ \ +--data @changed_file.json \ +https://_{foreman-example-com}_/api/smart_class_parameters/3 +---- diff --git a/guides/common/modules/proc_overriding-smart-class-parameters.adoc b/guides/common/modules/proc_overriding-smart-class-parameters.adoc new file mode 100644 index 00000000000..407668e9c26 --- /dev/null +++ b/guides/common/modules/proc_overriding-smart-class-parameters.adoc @@ -0,0 +1,92 @@ +[id="overriding-smart-class-parameters"] += Overriding Smart Class parameters + +You can search for Smart Parameters by using the API and supply a value to override a Smart Parameter in a Class. +You can find the full list of attributes that you can modify in the built-in API reference at `https://_{foreman-example-com}_/apidoc/v2/smart_class_parameters/update.html`. + +.Procedure +. Find the ID of the Smart Class parameter you want to change: +* List all Smart Class Parameters. ++ +Example request: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl --request GET --user _My_User_Name_:__My_Password__ \ +https://_{foreman-example-com}_/api/smart_class_parameters +---- ++ +* If you know the Puppet class ID, for example 5, you can restrict the scope: +Example request: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl --request GET --user _My_User_Name_:__My_Password__ \ +https://_{foreman-example-com}_/api/puppetclasses/5/smart_class_parameters +---- ++ +Both calls accept a search parameter. +You can view the full list of searchable fields in the {ProjectWebUI}. +Navigate to *Configure* > *Smart variables* and click in the search query box to reveal the list of fields. ++ +Two particularly useful search parameters are `puppetclass_name` and `key`, which you can use to search for a specific parameter. +For example, use the `--data` option to pass URL encoded data. ++ +Example request: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl --request GET --user _My_User_Name_:__My_Password__ \ +--data 'search=puppetclass_name = access_insights_client and key = authmethod' \ +https://_{foreman-example-com}_/api/smart_class_parameters +---- ++ +{Project} supports standard scoped-search syntax. +. When you find the ID of the parameter, list the full details including current override values. ++ +Example request: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl --request GET --user _My_User_Name_:__My_Password__ \ +https://_{foreman-example-com}_/api/smart_class_parameters/_63_ +---- +. Enable overriding of parameter values. ++ +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 '{"smart_class_parameter":{"override":true}}' \ +https://_{foreman-example-com}_/api/smart_class_parameters/63 +---- ++ +Note that you cannot create or delete the parameters manually. +You can only modify their attributes. +{Project} creates and deletes parameters only upon class import from {SmartProxies}. +. Add custom override matchers. ++ +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 '{"smart_class_parameter":{"override_value":{"match":"hostgroup=Test","value":"2.4.6"}}}' \ +https://_{foreman-example-com}_/api/smart_class_parameters/63 +---- ++ +For more information about override values, see `https://_{foreman-example-com}_/apidoc/v2/override_values.html`. +. You can delete override values. ++ +Example request: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl --request DELETE --user _My_User_Name_:__My_Password__ \ +https://_{foreman-example-com}_/api/smart_class_parameters/63/override_values/3 +---- diff --git a/guides/common/modules/proc_uploading-content-to-projectserver.adoc b/guides/common/modules/proc_uploading-content-to-projectserver.adoc new file mode 100644 index 00000000000..772071b7f3a --- /dev/null +++ b/guides/common/modules/proc_uploading-content-to-projectserver.adoc @@ -0,0 +1,283 @@ +[id="uploading-content-to-{project-context}-server"] += Uploading Content to {ProjectServer} + +You can use the {Project} API to upload and import large files to your {ProjectServer}. +This process involves four steps: + +. Create an upload request. +. Upload the content. +. Import the content. +. Delete the upload request. + +The maximum file size that you can upload is 2{nbsp}MB. +For information about uploading larger content, see xref:exam-API_Guide-Uploading_Content_Larger_than_2_MB[]. + +[id="proc-API_Guide-Uploading_Content_to_the_{Project}_Server"] +.Procedure +. Assign the package name to the variable `name`: ++ +Example request: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ export name=jq-1.6-2.el7.x86_64.rpm +---- +. Assign the checksum of the file to the variable `checksum`: ++ +Example request: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ export checksum=$(sha256sum $name|cut -c 1-65) +---- +. Assign the file size to the variable `size`: ++ +Example request: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ export size=$(du -bs $name|cut -f 1) +---- +. Create an upload request that returns the upload ID of the request by using `size` and `checksum`. ++ +Example request: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl -H 'Content-Type: application/json' -X POST -k \ +-u _My_User_Name_:__My_Password__ \ +-d "{\"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 request: ++ +[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 +---- +. Assign the path of the package you want to upload to the variable `path`: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ export path=/root/jq/jq-1.6-2.el7.x86_64.rpm +---- +. Upload your content. +Ensure you use the correct MIME type when you upload data. +The API uses the `application/json` MIME type for the requests to {Project} unless stated otherwise. +Combine the upload ID, MIME type, and other parameters to upload content. ++ +Example request: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl -u _My_User_Name_:__My_Password__ -H Accept:application/json -H \ +Content-Type:multipart/form-data --request PUT --data-urlencode size=$size --data-urlencode offset=0 \ +--data-urlencode content@$\{path} \ +https://_{foreman-example-com}_/katello/api/v2/repositories/76/content_uploads/$upload_id +---- +. After you have uploaded the content to your {ProjectServer}, you need to import it into the appropriate repository. +Until you complete this step, {ProjectServer} does not detect the new content. ++ +Example request: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl -H "Content-Type:application/json" -X PUT -u \ +_My_User_Name_:__My_Password__ -k -d \ +"{\"uploads\":[{\"id\": \"$upload_id\", \"name\": \"$name\", \ +\"checksum\": \"$checksum\" }]}" \ +https://_{foreman-example-com}_/katello/api/v2/repositories/76/import_uploads +---- +. After you have successfully uploaded and imported your content, you can delete the upload request. +This frees any temporary disk space that data is using during the upload. ++ +Example request: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl -H 'Content-Type: application/json' -X DELETE -k \ +-u _My_User_Name_:__My_Password__ -d "{}" \ +https://_{foreman-example-com}_/katello/api/v2/repositories/76/content_uploads/$upload_id +---- + +[id="exam-API_Guide-Uploading_Content_Larger_than_2_MB"] +.Uploading content larger than 2 MB + +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 -H 'Content-Type: application/json' -X POST -k \ +-u _My_User_Name_:__My_Password__ -d "{\"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 ++ +[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 +---- ++ +Example output ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ ls bpftool[0-9] -l +-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 -u _My_User_Name_:__My_Password__ -H Accept:application/json -H \ +Content-Type:multipart/form-data \ +-X PUT --data-urlencode size=$size --data-urlencode offset=0 \ +--data-urlencode content@$\{path}0 \ +https://_{foreman-example-com}_/katello/api/v2/repositories/76/content_uploads/$upload_id + +$ curl -u _My_User_Name_:__My_Password__ -H Accept:application/json -H \ +Content-Type:multipart/form-data \ +-X PUT --data-urlencode size=$size --data-urlencode offset=2000000 \ +--data-urlencode content@$\{path}1 \ +https://_{foreman-example-com}_/katello/api/v2/repositories/76/content_uploads/$upload_id + +$ curl -u _My_User_Name_:__My_Password__ -H Accept:application/json -H \ +Content-Type:multipart/form-data \ +-X PUT --data-urlencode size=$size --data-urlencode offset=4000000 \ +--data-urlencode content@$\{path}2 \ +https://_{foreman-example-com}_/katello/api/v2/repositories/76/content_uploads/$upload_id + +$curl -u _My_User_Name_:__My_Password__ -H Accept:application/json -H \ +Content-Type:multipart/form-data \ +-X PUT --data-urlencode size=$size --data-urlencode offset=6000000 +--data-urlencode content@$\{path}3 \ +https://_{foreman-example-com}_/katello/api/v2/repositories/76/content_uploads/$upload_id + +$ curl -u _My_User_Name_:__My_Password__ -H Accept:application/json -H \ +Content-Type:multipart/form-data \ +-X PUT --data-urlencode size=$size --data-urlencode offset=8000000 \ +--data-urlencode content@$\{path}4 \ +https://_{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 -H "Content-Type:application/json" -X PUT -u \ +_My_User_Name_:__My_Password__ -k -d \ +"{\"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 -H 'Content-Type: application/json' -X DELETE -k \ +-u _My_User_Name_:__My_Password__ -d "{}" \ +https://_{foreman-example-com}_/katello/api/v2/repositories/76/content_uploads/$upload_id +---- + +[id="exam-API_Guide-Uploading_Duplicate_Content"] +.Uploading duplicate content + +Note that if you try to upload duplicate content using: + +Example request: + +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl -H 'Content-Type: application/json' -X POST -k \ +-u _My_User_Name_:__My_Password__ -d "{\"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: +[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 -H "Content-Type:application/json" -X PUT -u \ +_My_User_Name_:__My_Password__ -k \-d \ +"{\"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-extended-searches.adoc b/guides/common/modules/proc_using-extended-searches.adoc new file mode 100644 index 00000000000..f3c150a4e9d --- /dev/null +++ b/guides/common/modules/proc_using-extended-searches.adoc @@ -0,0 +1,44 @@ +[id="using-extended-searches"] += Using extended searches + +You can find search parameters that you can use to build your search queries in the {ProjectWebUI}. +For more information, see {AdministeringDocURL}Building_Search_Queries_admin[Building search queries] in _{AdministeringDocTitle}_. + +For example, you can search for hosts. + +.Procedure +. In the {ProjectWebUI}, navigate to *Hosts* > *All Hosts* and click the *Search* field to display a list of search parameters. +. Locate the search parameters that you want to use. +For this example, locate *os_title* and *model*. +. Combine the search parameters in your API query as follows: ++ +Example request: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl --user _My_User_Name_:__My_Password__ \ +https://_{foreman-example-com}_/api/v2/hosts?search=os_title=\"RedHat+7.7\",model=\"PowerEdge+R330\" \ +| python3 -m json.tool +---- ++ +Example response: ++ +[options="nowrap", subs="+quotes,attributes"] +---- + { + ... + "results": [ + { + "model_id": 1, + "model_name": "PowerEdge R330", + "name": "_{foreman-example-com}_", + "operatingsystem_id": 1, + "operatingsystem_name": "RedHat 7.7", + ... + } + ], + "search": "os_title=\"RedHat 7.7\",model=\"PowerEdge R330\"", + "subtotal": 1, + "total": 11 +} +---- diff --git a/guides/common/modules/proc_using-searches-with-pagination-control.adoc b/guides/common/modules/proc_using-searches-with-pagination-control.adoc new file mode 100644 index 00000000000..5fda7b839e4 --- /dev/null +++ b/guides/common/modules/proc_using-searches-with-pagination-control.adoc @@ -0,0 +1,48 @@ +[id="using-searches-with-pagination-control"] += Using searches with pagination control + +You can use the `per_page` and `page` pagination parameters to limit the search results that an API search query returns. +The `per_page` parameter specifies the number of results per page and the `page` parameter specifies which page, as calculated by the `per_page` parameter, to return. + +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: +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl --request GET --user _My_User_Name_:__My_Password__ \ +https://{foreman-example-com}/katello/api/activation_keys?organization_id=1&per_page=30&page=2 +---- + +[id="ex-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: + +[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 new file mode 100644 index 00000000000..e73aa711824 --- /dev/null +++ b/guides/common/modules/proc_using-the-delete-http-method.adoc @@ -0,0 +1,35 @@ +[id="using-the-delete-http-method"] += 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. + +.Example +This example deletes the `TestKey` activation key which ID is 2: + +Example request: +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl \ +--header "Accept:application/json" \ +--header "Content-Type:application/json" \ +--request DELETE \ +--user _My_User_Name_:__My_Password__ \ +https://_{foreman-example-com}_/katello/api/activation_keys/2 \ +| python3 -m json.tool +---- + +Example response: +[options="nowrap", subs="+quotes,attributes"] +---- +_output omitted_ + "started_at": "2017-02-16 12:58:17 UTC", + "ended_at": "2017-02-16 12:58:18 UTC", + "state": "stopped", + "result": "success", + "progress": 1.0, + "input": { + "activation_key": { + "id": 2, + "name": "TestKey" +_output truncated_ +---- diff --git a/guides/common/modules/proc_using-the-get-http-method.adoc b/guides/common/modules/proc_using-the-get-http-method.adoc new file mode 100644 index 00000000000..cae35ed9d99 --- /dev/null +++ b/guides/common/modules/proc_using-the-get-http-method.adoc @@ -0,0 +1,34 @@ +[id="using-the-get-http-method"] += Using the GET HTTP method + +Use the GET HTTP method to get data from the API about an existing entry or resource. + +.Example +This example requests the amount of {Project} hosts: + +Example request: +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl --request GET --user _My_User_Name_:__My_Password__ \ +https://_{foreman-example-com}_/api/hosts | python3 -m json.tool +---- + +Example response: +[options="nowrap", subs="+quotes,attributes"] +---- +{ + "total": 2, + "subtotal": 2, + "page": 1, + "per_page": 20, + "search": null, + "sort": { + "by": null, + "order": null + }, + "results": +_output truncated_ +---- + +The response from the API indicates that there are two results in total, this is the first page of the results, and the maximum results per page is set to 20. +For more information, see xref:json-response-format[]. diff --git a/guides/common/modules/proc_using-the-post-http-method.adoc b/guides/common/modules/proc_using-the-post-http-method.adoc new file mode 100644 index 00000000000..d3084a04b5d --- /dev/null +++ b/guides/common/modules/proc_using-the-post-http-method.adoc @@ -0,0 +1,73 @@ +[id="using-the-post-http-method"] += Using the POST HTTP method + +Use the POST HTTP verb to submit data to the API to create an entry or resource. +You must submit the data in JSON format. +For more information, see xref:sect-API_Guide-Passing_JSON_Data_with_the_API_Request[]. + +.Example to create an activation key + +. Create a test file, for example, `activation-key.json`, with the following content: ++ +[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: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl --header "Accept:application/json" \ +--header "Content-Type:application/json" --request POST \ +--user _My_User_Name_:__My_Password__ \ +--data @activation-key.json \ +https://_{foreman-example-com}_/katello/api/activation_keys \ +| python3 -m json.tool +---- ++ +Example response: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +{ + "id": 2, + "name": "TestKey", + "description": "Just for testing", + "unlimited_hosts": true, + "auto_attach": true, + "content_view_id": null, + "environment_id": null, + "usage_count": 0, + "user_id": 3, + "max_hosts": null, + "release_version": null, + "service_level": null, + "content_overrides": [ + + ], + "organization": { + "name": "Default Organization", + "label": "Default_Organization", + "id": 1 + }, + "created_at": "2017-02-16 12:37:47 UTC", + "updated_at": "2017-02-16 12:37:48 UTC", + "content_view": null, + "environment": null, + "products": null, + "host_collections": [ + + ], + "permissions": { + "view_activation_keys": true, + "edit_activation_keys": true, + "destroy_activation_keys": true + } +} +---- + +. Verify that the new activation key is present. +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 new file mode 100644 index 00000000000..b52651085ef --- /dev/null +++ b/guides/common/modules/proc_using-the-put-http-method.adoc @@ -0,0 +1,75 @@ +[id="using-the-put-http-method"] += Using the PUT HTTP method + +Use the PUT HTTP method to change an existing value or append to an existing resource. +You must submit the data in JSON format. +For more information, see xref:sect-API_Guide-Passing_JSON_Data_with_the_API_Request[]. + +.Example + +This example updates the `TestKey` activation key created in the previous example. + +. Edit the `activation-key.json` file created previously as follows: ++ +[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: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl --request PUT \ +--header "Accept:application/json" \ +--header "Content-Type:application/json" \ +--user _My_User_Name_:__My_Password__ \ +--data @activation-key.json \ +https://_{foreman-example-com}_/katello/api/activation_keys/2 \ +| python3 -m json.tool +---- ++ +Example response: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +{ + "id": 2, + "name": "TestKey", + "description": "Just for testing", + "unlimited_hosts": false, + "auto_attach": true, + "content_view_id": null, + "environment_id": null, + "usage_count": 0, + "user_id": 3, + "max_hosts": 10, + "release_version": null, + "service_level": null, + "content_overrides": [ + + ], + "organization": { + "name": "Default Organization", + "label": "Default_Organization", + "id": 1 + }, + "created_at": "2017-02-16 12:37:47 UTC", + "updated_at": "2017-02-16 12:46:17 UTC", + "content_view": null, + "environment": null, + "products": null, + "host_collections": [ + + ], + "permissions": { + "view_activation_keys": true, + "edit_activation_keys": true, + "destroy_activation_keys": true + } +} +---- + +. 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 new file mode 100644 index 00000000000..7541001f28f --- /dev/null +++ b/guides/common/modules/proc_working-with-hosts.adoc @@ -0,0 +1,201 @@ +[id="working-with-hosts"] += Working with 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: +[options="nowrap", subs="+quotes,attributes"] +---- +{ + ... + "total" => 2, + "subtotal" => 2, + "page" => 1, + "per_page" => 1000, + "search" => nil, + "sort" => { + "by" => nil, + "order" => nil + }, + "results" => [ + ... +} +---- + +.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: +[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, + ... +} +---- + +.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: +[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", + ... +} +---- + +.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: +[options="nowrap", subs="+quotes,attributes"] +---- +{ + ... + "results": [ + { + "name": "_{foreman-example-com}_", + ... + } + ], + "search": "example", + ... +} +---- + +.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: +[options="nowrap", subs="+quotes,attributes"] +---- +{ + ... + "results": [ + { + "environment_name": "production", + "name": "_{foreman-example-com}_", + ... + } + ], + "search": "environment=production", + ... +} +---- + +.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: +[options="nowrap", subs="+quotes,attributes"] +---- +{ + ... + "results": [ + { + "model_id": 1, + "model_name": "RHV Hypervisor", + "name": "_{foreman-example-com}_", + ... + } + ], + "search": "model=\"RHV Hypervisor\"", + ... +} +---- + +.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 +---- + +.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__ \ +https://_{foreman-example-com}_/api/bootdisk/hosts/_host_ID_?full=true \ +--output _image_.iso +---- diff --git a/guides/common/modules/proc_working-with-lifecycle-environments.adoc b/guides/common/modules/proc_working-with-lifecycle-environments.adoc new file mode 100644 index 00000000000..43198815865 --- /dev/null +++ b/guides/common/modules/proc_working-with-lifecycle-environments.adoc @@ -0,0 +1,233 @@ +[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`. + +.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: +[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="proc-Creating_Linked_Life_Cycle_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. + +. 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`: ++ +Example request: ++ +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl --request GET --user _My_User_Name_:__My_Password__ \ +https://_{foreman-example-com}_/katello/api/environments/1 \ +| python3 -m json.tool +---- ++ +Example response: ++ +[options="nowrap", subs="+quotes,attributes"] +---- + _output omitted_ + *"id": 1,* + *"label": "Library",* + _output omitted_ + *"prior": null,* + *"successor": null,* + _output truncated_ +---- +. Create a JSON file, for example, `life-cycle.json`, with the following content: ++ +---- +{"organization_id":1,"label":"api-dev","name":"API Development","prior":1} +---- +. Create a lifecycle environment by using the `prior` option set to `1`. ++ +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 @life-cycle.json \ +https://_{foreman-example-com}_/katello/api/environments \ +| python3 -m json.tool +---- ++ +Example response: ++ +[options="nowrap", subs="+quotes,attributes"] +---- + _output omitted_ + "description": null, + *"id": 2,* + "label": "api-dev", + "library": false, + "name": "API Development", + "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": 1,* + "name": "Library" + }, + _output truncated_ +---- ++ +In the command output, you can see the ID for this lifecycle environment is `2`, and the lifecycle environment before this one is `1`. +Use the lifecycle environment with ID `2` to create a successor to this environment. +. Edit the previously created `life-cycle.json` file, updating the `label`, `name`, and `prior` values. ++ +---- +{"organization_id":1,"label":"api-qa","name":"API QA","prior":2} +---- +. Create a lifecycle environment, by using the `prior` option set to `2`. ++ +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 @life-cycle.json \ +https://_{foreman-example-com}_/katello/api/environments \ +| python3 -m json.tool +---- ++ +Example response: ++ +[options="nowrap", subs="+quotes,attributes"] +---- + _output omitted_ + "description": null, + *"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" + }, + "successor": null, + _output truncated_ +---- ++ +In the command output, you can see the ID for this lifecycle environment is `3`, and the lifecycle environment before this one is `2`. + + +.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: +[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_ +---- + +.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/ref_api-response-codes.adoc b/guides/common/modules/ref_api-response-codes.adoc new file mode 100644 index 00000000000..031b6ab8a62 --- /dev/null +++ b/guides/common/modules/ref_api-response-codes.adoc @@ -0,0 +1,25 @@ +[id="api-response_codes"] += API response codes + +The {ProjectNameX} API provides HTTP response status codes for API calls. +The following codes are common for all resources in the {Project} API. + +.API response codes +[cols="2,5" options="header"] +|==== +|Response |Explanation +|200 OK |For a successful request action: show, index, update, or delete (GET, PUT, DELETE requests). +|201 Created |For a successful create action (POST request). +|301 Moved Permanently |Redirect when {Project} is restricted to use HTTPS and HTTP is attempted. +|400 Bad Request |A required parameter is missing or the search query has invalid syntax. +|401 Unauthorized |Failed to authorize the user, for example, due to incorrect credentials. +|403 Forbidden |The user has insufficient permissions to perform the action or read the resource, or the action is unsupported in general. +|404 Not Found |The record with the given ID does not exist. +It can appear in show and delete actions when the requested record does not exist; or in create, update and delete actions when one of the associated records does not exist. +|409 Conflict |Could not delete the record due to existing dependencies, for example, host groups that still contain hosts. +|415 Unsupported Media Type |The content type of the HTTP request is not JSON. +|422 Unprocessable Entity |Failed to create an entity due to some validation errors. +Applies to create or update actions only. +|500 Internal Server Error |Unexpected internal server error. +|503 Service Unavailable |The server is not running. +|==== diff --git a/guides/common/modules/ref_json-response-format.adoc b/guides/common/modules/ref_json-response-format.adoc new file mode 100644 index 00000000000..9d996e9dfe1 --- /dev/null +++ b/guides/common/modules/ref_json-response-format.adoc @@ -0,0 +1,104 @@ +[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": "2013-08-13T09:02:31Z", + "updated_at": "2013-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: +[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": "2013-08-13T09:02:31Z", + "updated_at": "2013-08-13T09:02:31Z" + }, + { + "id": 25, + "name": "dev.lab.example.com", + "fullname": "DEVEL", + "dns_id": 8, + "created_at": "2013-08-13T08:32:48Z", + "updated_at": "2013-08-14T07:04:03Z" + }, + { + "id": 32, + "name": "hr.lab.example.com", + "fullname": "HR", + "dns_id": 8, + "created_at": "2013-08-16T08:32:48Z", + "updated_at": "2013-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_oauth-request-format.adoc b/guides/common/modules/ref_oauth-request-format.adoc new file mode 100644 index 00000000000..620ce84c493 --- /dev/null +++ b/guides/common/modules/ref_oauth-request-format.adoc @@ -0,0 +1,29 @@ +[id="oauth-request-format"] += OAuth request format + +Every OAuth API request requires the `FOREMAN-USER` header with the login of an existing {Project} user and the `Authorization` header in the following format: + +[options="nowrap", subs="+quotes,attributes"] +---- +--header 'FOREMAN-USER: __My_User_Name__' \ +--header 'Authorization: OAuth oauth_version="1.0",oauth_consumer_key="_secretkey_",oauth_signature_method="hmac-sha1",oauth_timestamp=_timestamp_,oauth_signature=_signature_' +---- + +IMPORTANT: Use an OAuth client library to construct all OAuth parameters. +For an example that uses the *requests_oauthlib* Python module, see https://access.redhat.com/solutions/4240401[How to execute an API call by using the OAuth authentication method via python script in {ProjectNameX}?] in the _Red{nbsp}Hat Knowledgebase_. + +.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: +[options="nowrap", subs="+quotes,attributes"] +---- +$ curl 'https://_{foreman-example-com}_/api/architectures' \ +--header 'Content-Type: application/json' \ +--header 'Accept:application/json' \ +--header 'FOREMAN-USER: _My_User_Name_' \ +--header 'Authorization: OAuth oauth_version="1.0",oauth_consumer_key="_secretkey_",oauth_signature_method="hmac-sha1",oauth_timestamp=_1321473112_,oauth_signature=_Il8hR8/ogj/XVuOqMPB9qNjSy6E=_' +---- diff --git a/guides/common/modules/ref_relating-api-error-messages-to-the-api-reference.adoc b/guides/common/modules/ref_relating-api-error-messages-to-the-api-reference.adoc new file mode 100644 index 00000000000..244ae76a146 --- /dev/null +++ b/guides/common/modules/ref_relating-api-error-messages-to-the-api-reference.adoc @@ -0,0 +1,16 @@ +[id="relating-api-error-messages-to-the-api-reference"] += Relating API error messages to the API reference + +The API uses a RAILs format to indicate an error: + +[options="nowrap", subs="+quotes,attributes"] +---- +_Nested_Resource_._Attribute_Name_ +---- + +This translates to the following format used in the API reference: + +[options="nowrap", subs="+quotes,attributes"] +---- +_Resource_[_Nested_Resource_attributes_][_Attribute_Name_id_] +---- diff --git a/guides/doc-Project_API/Makefile b/guides/doc-Project_API/Makefile new file mode 100644 index 00000000000..dd1e5be8557 --- /dev/null +++ b/guides/doc-Project_API/Makefile @@ -0,0 +1 @@ +include ../common/Makefile diff --git a/guides/doc-Project_API/common b/guides/doc-Project_API/common new file mode 120000 index 00000000000..83323993bad --- /dev/null +++ b/guides/doc-Project_API/common @@ -0,0 +1 @@ +../common/ \ No newline at end of file diff --git a/guides/doc-Project_API/docinfo.xml b/guides/doc-Project_API/docinfo.xml new file mode 100644 index 00000000000..f423515c9da --- /dev/null +++ b/guides/doc-Project_API/docinfo.xml @@ -0,0 +1,13 @@ +{APIDocTitle} +Red Hat Satellite +{ProjectVersion} +Develop custom applications or integrations by using the Satellite REST API +The Red Hat Satellite Representational State Transfer (REST) API guide explains the concepts behind a REST API and provides example usage for various types of requests. This provides a basis for administrators and developers to write custom scripts and integrate Red Hat Satellite with third-party applications. + + + Red Hat Satellite + Documentation Team + satellite-doc-list@redhat.com + + + diff --git a/guides/doc-Project_API/images/common b/guides/doc-Project_API/images/common new file mode 120000 index 00000000000..ac7700aa2af --- /dev/null +++ b/guides/doc-Project_API/images/common @@ -0,0 +1 @@ +../common/images/ \ No newline at end of file diff --git a/guides/doc-Project_API/master.adoc b/guides/doc-Project_API/master.adoc new file mode 100644 index 00000000000..c08dc90f719 --- /dev/null +++ b/guides/doc-Project_API/master.adoc @@ -0,0 +1,36 @@ +include::common/attributes.adoc[] +include::common/header.adoc[] +:context: rest-api +:rest-api: + += {APIDocTitle} + +// This guide is not ready for stable releases +ifdef::HideDocumentOnStable[] +include::common/modules/snip_guide-not-ready.adoc[] +endif::[] +ifndef::HideDocumentOnStable[] + +ifdef::satellite[] +include::common/modules/proc_providing-feedback-on-red-hat-documentation.adoc[leveloffset=+1] +endif::[] + +include::common/assembly_introduction-to-project-api.adoc[leveloffset=+1] + +include::common/modules/proc_accessing-the-built-in-api-reference.adoc[leveloffset=+1] + +include::common/assembly_api-syntax.adoc[leveloffset=+1] + +include::common/assembly_api-call-authentication.adoc[leveloffset=+1] + +include::common/assembly_api-requests-in-various-languages.adoc[leveloffset=+1] + +include::common/assembly_api-cheat-sheet.adoc[leveloffset=+1] + +[appendix] +include::common/modules/ref_api-response-codes.adoc[leveloffset=+1] + +[appendix] +include::common/modules/proc_creating-a-complete-permission-table.adoc[leveloffset=+1] + +endif::[]