Upstreamize API guide

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]

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]

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]

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]

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]

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

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}

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

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
 

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.

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[].

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.

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.

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.
+====

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.

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.

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]

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.

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}_].

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::[]

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.

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}.

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
+----