Merge pull request #522 from mulesoft/W-13570214-final-split-upstream-downstream-gr

W-13570214 final split upstream downstream gr

Author: glenn-rodgers-sf

modules/ROOT/nav.adoc

@@ -3,16 +3,18 @@
 * xref:api-manager-release-notes.adoc[Release Notes]
 * xref:getting-started-proxy.adoc[Get Started with Managing an API]
 * xref:api-instance-landing-page.adoc[Manage API Instances]
- ** xref:create-instance-task.adoc[Add an API Instance]
- ** xref:manage-exchange-api-task.adoc[Add an API Instance on a Self-Managed Server]
- ** xref:configure-api-task.adoc[Configure an API Instance]
+ ** xref:add-api-instances.adoc[Add API Instances]
+ *** xref:create-instance-task-flex.adoc[Add a Flex Gateway API Instance]
+ *** xref:create-instance-task-mule.adoc[Add a Mule Gateway API Instance]
+ *** xref:create-instance-task-service-mesh.adoc[Add a Service Mesh API Instance]
+ *** xref:manage-exchange-api-task.adoc[Add an API Instance on a Self-Managed Server]
  ** xref:find-api-id-task.adoc[Obtain an API Instance ID]
  ** xref:export-api-latest-task.adoc[Export an API Instance]
  ** xref:access-developer-portal-task.adoc[Access the Developer Portal]
- ** xref:edit-api-endpoint-task.adoc[Edit an API Instance Endpoint]
+ ** xref:edit-api-endpoint-task.adoc[Edit an API Instance]
  ** xref:deprecate-api-latest-task.adoc[Deprecate an API Instance]
  ** xref:delete-api-task.adoc[Delete an API Instance]
- ** xref:manage-versions-instances-concept.adoc[Manage API Versions and Instances]
+ ** xref:manage-versions-instances-concept.adoc[Manage API Instance Versions]
  ** xref:configure-multiple-credential-providers.adoc[Configure Multiple Client Provider]
 * xref:api-groups-landing-page.adoc[Manage API Groups]
  ** xref:api-groups-creating-groups.adoc[Create API Groups]

modules/ROOT/pages/_partials/api-configuration-tables.adoc

@@ -0,0 +1,90 @@
+//tag::flex-downstream[]
+[%header%autowidth.spread,cols="15%,35%,15%,35%"]
+|===
+| Field Name | Description | Required | Notes
+| *Protocol* | Specifies whether to use HTTP or HTTPS. | Yes | If you select HTTPS, specify a TLS context for inbound traffic.
+| *Inbound TLS* | Specifies the TLS Context used for the inbound traffic of HTTPS APIs. | No | xref:gateway::flex-conn-tls-config.adoc[Configure a TLS Context for Flex Gateway] before adding a TLS Context to your API. Only available on Flex 1.4.0+.
+| *Port* | Specifies the number to use if the displayed port is incorrect. | No | Port can be shared between API instances over the same Target as long as the Base paths are different. Only available on Flex 1.2.0+.
+| *Instance label* | Specifies a label for the API. | No | If you have multiple managed instances of the same API, add a label to differentiate each instance from the others.
+| *Advanced Options* |  |  |
+| *Consumer endpoint* | Specifies a proxy application's address for consumers to use for sending requests.| No |
+| *Client provider* | Specifies a client provider for the API. | No | Anypoint Platform acts as the client provider by default. To configure an external client provider, see xref:access-management::managing-api-clients.adoc[Client Providers]. 
+|===
+//end::flex-downstream[]
+
+//tag::flex-upstream[]
+[%header%autowidth.spread,cols="15%,35%,15%,35%"]
+|===
+| Field Name | Description | Required | Notes
+| *Upstream URL* | The URL to access for the proxy or the API. It must end with a /. | Yes|  For example, you can use the URL of your API asset in Exchange. 
+| *Outbound TLS* | Specifies the TLS Context used for the outbound traffic. | No | xref:gateway::flex-conn-tls-config.adoc[Configure a TLS Context for Flex Gateway] before adding a TLS Context to your API. Only available on Flex 1.4.0+.
+|===
+//end::flex-upstream[]
+
+//tag::service-mesh-downstream[]
+[%header%autowidth.spread,cols="15%,35%,15%,35%"]
+|===
+| Field Name | Description | Required | Notes
+| *Instance label* | Specifies a label for the API. | No | If you have multiple managed instances of the same API, add a label to differentiate each instance from the others.
+| *Advanced Options* |  |  |
+| *Consumer endpoint* | Specifies a proxy application's address for consumers to use for sending requests.| No |
+| *Client provider* | Specifies a client provider for the API. | Yes | Anypoint Platform acts as the client provider by default. To configure an external client provider, see xref:access-management::managing-api-clients.adoc[Client Providers]. 
+|===
+//end::service-mesh-downstream[]
+
+//tag::service-mesh-upstream[]
+[%header%autowidth.spread,cols="15%,35%,15%,35%"]
+|===
+| Field Name | Description | Required | Notes
+| *Upstream URL* | The URL to access for the proxy or the API. | No |  For example, you can use the URL of your API asset in Exchange. 
+|===
+//end::service-mesh-upstream[]
+
+//tag::mule-app-downstream[]
+[%header%autowidth.spread,cols="15%,35%,15%,35%"]
+|===
+| Field Name | Description | Required | Notes
+| *Instance label* | Specifies a label for the API. | No | If you have multiple managed instances of the same API, add a label to differentiate each instance from the others.
+| *Advanced Options* |  |  |
+| *Consumer endpoint* | Specifies a proxy application's address for consumers to use for sending requests.| No |
+| *Client provider* | Specifies a client provider for the API. | Yes | Anypoint Platform acts as the client provider by default. To configure an external client provider, see xref:access-management::managing-api-clients.adoc[Client Providers]. 
+|===
+//end::mule-app-downstream[]
+
+//tag::mule-app-upstream[]
+[%header%autowidth.spread,cols="15%,35%,15%,35%"]
+|===
+| Field Name | Description | Required | Notes
+| *Upstream URL* | The URL to access for the proxy or the API. | No |  For example, you can use the URL of your API asset in Exchange. 
+|===
+//end::mule-app-upstream[]
+
+//tag::mule-proxy-downstream[]
+[%header%autowidth.spread,cols="15%,35%,15%,35%"]
+|===
+| Field Name | Description | Required | Notes
+| *Protocol* | Specifies whether to use HTTP or HTTPS for the validations. | Yes | If you select HTTPS, specify a TLS context for inbound traffic.
+| *Inbound TLS* | Specifies the TLS context to secure inbound traffic. | No |  Only available on Mule 4+. If you can't see a context, ensure that you have the correct permissions.
+| *Port* | Specifies the number to use if the displayed port is incorrect. | Yes | 
+| *Base path* | Specifies the URL prefix for all API paths, relative to the host root. It must start with a leading slash /. | Yes | 
+| *Instance label* | Specifies a label for the API. | No | If you have multiple managed instances of the same API, add a label to differentiate each instance from the others.
+| *Advanced Options* |  |  |
+| *Consumer endpoint* | Specifies a proxy application's address for consumers to use for sending requests.| No |
+| *Client provider* | Specifies a client provider for the API. | Yes | Anypoint Platform acts as the client provider by default. To configure an external client provider, see xref:access-management::managing-api-clients.adoc[Client Providers].
+| *Request timeout* | Specifies the duration after which a request times out. | No | 
+| *Proxy Version* | Specifies the version of the proxy to use for the endpoint.| No |
+| *Enable Console* | Specifies whether you can expose and test your API specification. | No | You can specify a different path in *Console Path*, for example, "/spec/*". Only available if you have an attached API definition. Only available on Mule 3+.
+| *Validations* | Specifies whether to validate inbound requests against a provided specification. | No | Only available if you have an attached API definition. Only available on Mule 3+.
+| *Strict validations (optional)* | Specifies whether to validate inbound requests against query parameters. | No | Only available if you have an attached API definition. Only available on Mule 3+
+| *User Domain* | Specifies whether to use an API gateway domain. | No | If you chose *Hybrid* as the proxy deployment target previously in the configuration, ensure that you select this option. You must install the API gateway domain in Mule 3.8 and later.
+|===
+//end::mule-proxy-downstream[]
+
+//tag::mule-proxy-upstream[]
+[%header%autowidth.spread,cols="15%,35%,15%,35%"]
+|===
+| Field Name | Description | Required | Notes
+| *Upstream URL* | The URL to access for the proxy or the API. | Yes|  For example, you can use the URL of your API asset in Exchange. 
+| *Outbound TLS* | Specifies the TLS context to secure outbound traffic.  | No |  Only available on Mule 4+. If you can't see a context, ensure that you have the correct permissions.
+|===
+//end::mule-proxy-upstream[]

modules/ROOT/pages/_partials/task-add-api-instance.adoc

@@ -0,0 +1,36 @@
+//tag::intro1[]
+After you have created an API using Design Center or any other application, you can then manage that API in API Manager by adding an API instance. API instances remain under management until you delete them.
+
+//end::intro1[]
+
+//tag::flex-intro[]
+Use Flex Gateway for any APIs that need a flexible and performant API gateway
+that works with distributed and microservices environments and fits into your CI/CD environments.
+
+//end::flex-intro[]
+
+//tag::mule-intro[]
+Use Mule Gateway if you have APIs on Mule Runtime that need an API gateway to manage, observe,
+and secure your APIs.
+
+//end::mule-intro[]
+
+//tag::service-mesh-intro[]
+Use Service Mesh to extend Anypoint Platform API Management capabilities to your
+Istio service mesh through the deployment of a Mule Adapter.
+
+//end::service-mesh-intro[]
+
+//tag::intro2[]
+
+There are three options for adding an API instance:
+
+* <<add-api, *Add a new API:*>> Select this option to add a completely new instance of an API.
+* <<promote-api, *Promote API from environment:*>> Select this option if you have an API instance in a different environment, for instance
+the sandbox environment, and you want to promote it to the current or production environment.
+* <<import-api, *Import API from zip file:*>> Select this option if you have exported an API instance from a different Anypoint Platform
+instance.
+
+When you are promoting or importing an API instance, you do not have options to alter the configuration. However, when you add a new API instance, you need to the downstream and the upstream configuration settings.
+
+//end::intro2[]

modules/ROOT/pages/_partials/task-configure-proxy.adoc

@@ -35,6 +35,11 @@ Select the *Target type* from the following options:
 CloudHub 2.0 proxy includes a CPU with 0.1 vCores by default.
 .. Select the **Runtime version**.
 .. Enter a **Proxy app name**.
++
+[NOTE]
+--
+When deploying an API directly to CloudHub 2.0, you cannot choose the region where the API is deployed. If you have a private space, your API is deployed to your private space. Otherwise, your API is deployed to the shared space in your default region. If you have multiple private spaces, a private space is chosen for you. Private spaces in your default region are chosen first. To learn more about spaces, see xref:cloudhub-2::ch2-shared-space-about.adoc[] and xref:cloudhub-2::ch2-private-space-about.adoc[].
+--
 * *CloudHub*: Select this option if you want to use the Mule runtime hosted on the cloud by MuleSoft. The
 CloudHub proxy includes a CPU with 0.1 vCores and a memory of 500 MB, by default.
 .. Select the **Runtime version**.
@@ -91,7 +96,7 @@ NOTE: After adding the API on Anypoint Platform, you will need to bind it to a s
 
 ** **REST API:** Select this option if you have a RAML or OAS API definition file you want to include for your asset.
 +
-Upload either a RAML or OAS file for your REST API.
+Upload either a RAML or OAS file for your REST API. Versions 2.0.0 and later are the recommended versions for OAS or RAML specs, because these versions add native OAS support. If you upload an OAS API specification to an API proxy version 1.0 or earlier, your API specification is translated to RAML.
 ** **HTTP API:** Select this option if you do not have an API definition file you want to include for your asset.
 ** **SOAP API:** Select this option if you have a WSDL API definition file or an external link to the file.
 +
@@ -103,7 +108,7 @@ This option is not available for Flex Gateway runtime at this time.
 //end::asset-type-options[]
 //tag::raml-oas[]
 .. Select **REST API** as the **Asset type**.
-.. Upload either a RAML or OAS file for your REST API.
+.. Upload either a RAML or OAS file for your REST API. 
 +
 NOTE: Anypoint API Manager supports OpenAPI Specification (OAS) 3.0, with the exception of the callback feature. To work around this issue, handle the callback outside of the Mule runtime engine domain or use an OAS 3.0 specification that does not use callbacks.
 
@@ -119,21 +124,24 @@ NOTE: Anypoint API Manager supports OpenAPI Specification (OAS) 3.0, with the ex
 [[configure_options]]
 = Configure Options
 
-. Enter your *Implementation URI*. The Implementation URI is the URL to access the proxy or the API. For example, you can use the URL of your API asset in Exchange. +
-This is the only required field. For further details on the optional fields, see xref:configure-api-task.adoc[Configure an API Endpoint].
-. If you want to enable SSL for inbound traffic:
-** Select **HTTPS** for the **Scheme**. +
-You should now see the **TLS Context for Inbound Traffic** field enabled.
-** Select **Add TLS Context**.
-*** Select the secret group where you hosted your TLS context from the **Secret group** drop-down.
-*** Select your TLS context for your HTTPS API Proxy from the **TLS Context** drop-down.
+
+. If you want to enable TSL for inbound traffic:
+** Select *HTTPS* for the *Scheme*. +
+You should now see the *Inbound TLS* field enabled.
+** Select *Add TLS Context*.
+*** Select the secret group where you hosted your TLS context from the *Secret group* drop-down.
+*** Select your TLS context for your HTTPS API Proxy from the *TLS Context* drop-down.
 . Enter the *Port* number for your API proxy.
-. Select your *Client Provider*.
+. Enter the *Base path*.
 . Click *Advanced Options*.
+. Select optional downstream configuration settings. For more configuration settings, see xref:create-instance-task-mule.adoc[].
 . In *Proxy Version*, select *latest*. +
 This value ensures that your API proxy uses the latest released proxy version.
 If a new proxy version is available in Anypoint platform, return to this step to reconfigure your proxy to the latest version.
-. Click *Add TLS Context* for *TLS Context for Outbound traffic*.
+. Click *Next*.
+. Enter your *Upstream URL*. This is the URL to access the proxy or the API. For example, you can use the URL of your API asset in Exchange. +
+This is the only required field. For further details on the optional fields, see xref:configure-api-task.adoc[Configure an API Endpoint].
+. Click *Add TLS Context* for *Outbound TLS*. This is required for API instances using HTTPs communication.
 .. Select the secret group where you hosted your TLS Context from the *Secret Group* drop-down list.
 .. Select your TLS Context for your HTTPS API Proxy from the *TLS Context* drop-down.
 +
@@ -144,8 +152,8 @@ If you can't see a context, check that you have the right permissions, as mentio
 //end::mid-steps2[]
 //tag::raml-oas-version[]
 +
-Versions 2.0.0 and later are the recommended versions for OAS or RAML specs, because these versions add native OAS support. +
-If you upload an OAS API specification to an API proxy version 1.0 or earlier, your API specification will be translated to RAML.
+Versions 2.0.0 and later are the recommended versions for OAS or RAML specs, because these versions add native OAS support.
+If you upload an OAS API specification to an API proxy version 1.0 or earlier, your API specification is translated to RAML.
 +
 //end::raml-oas-version[]
 //tag::tls[]

modules/ROOT/pages/_partials/task-import-api.adoc

@@ -0,0 +1,8 @@
+[[import-api]]
+== Import API from Zip File
+
+. Navigate to *Anypoint Platform* > *API Manager*.
+. From *API Administration*, click **Add API** and select **Import API from zip file**.
+. Click **Choose file** and select your API instance configuration zip file.
+. Click **Next**.
+. Review and update the API Configuration details as needed and click **Save**.

modules/ROOT/pages/_partials/task-promote-api.adoc

@@ -0,0 +1,12 @@
+[[promote-api]]
+== Promote API from Environment
+
+. Navigate to *Anypoint Platform* > *API Manager*. 
+. In *API Administration*, click **Add API** and select **Promote API from environment**.
+. Select the **Source Environment**.
+. Select the **API** by entering the name of the API into the search field.
+. Select the **API Version**.
+. Select the **API instance label**.
+. Optionally, uncheck any of the **Include in Promotion** options you want to exclude.
+. Click **Promote**.
+. Review and update the Runtime & Endpoint Configuration details as needed and click **Save**.

modules/ROOT/pages/add-api-instances.adoc

@@ -0,0 +1,13 @@
+= Add API Instances
+ifndef::env-site,env-github[]
+include::_attributes.adoc[]
+endif::[]
+
+* xref:create-instance-task-flex.adoc[] +
+include::partial$task-add-api-instance.adoc[tags=flex-intro]
+* xref:create-instance-task-mule.adoc[] +
+include::partial$task-add-api-instance.adoc[tags=mule-intro]
+* xref:create-instance-task-service-mesh.adoc[] +
+include::partial$task-add-api-instance.adoc[tags=service-mesh-intro]
+* xref:manage-exchange-api-task.adoc[] +
+Use a Hybrid deployment type to add API instances to self-managed servers.

modules/ROOT/pages/api-instance-landing-page.adoc

@@ -2,6 +2,7 @@
 ifndef::env-site,env-github[]
 include::_attributes.adoc[]
 endif::[]
+:page-aliases: create-instance-task.adoc, configure-api-task.adoc
 :keywords: api, instance, manager
 
 An API instance is the instantiation of an API definition. It is an object that is used to share data between gateways and the control plane. An API instance can either be a proxy of an API that serves the upstream or a Mule application endpoint.
@@ -12,14 +13,16 @@ You can create one instance of an API version that serves as a proxy and create
 
 To manage API instances in API Manager:
 
-. xref:create-instance-task.adoc[Add an API Instance] - API instances are managed by API Manager after you add them and remain under management until you delete them. 
-. xref:configure-api-task.adoc[Configure an API Instance] - You can customize your API instance to fit your specific situation with many optional settings. Not all options are available depending on the runtime as well as the API.
+. Add an API instance for your relevant gateway:
+** xref:create-instance-task-flex.adoc[Add a Flex Gateway API Instance]
+** xref:create-instance-task-mule.adoc[Add a Mule Gateway API Instance] 
+** xref:create-instance-task-service-mesh.adoc[Add a Service Mesh API Instance]
 . View an API instance's API Summary for information about the instance or to export it:
 ** xref:find-api-id-task.adoc[Obtain API Instance ID] - API Manager generates the apiId of new APIs managed by API Manager for use with Mule 4.
 ** xref:export-api-latest-task.adoc[Export an API Instance] - After creating an API instance, you can export it. This exports the API instance endpoint configuration and Exchange asset relationship. You can then import it into another environment in the same business group to create a new API instance.
 ** xref:access-developer-portal-task.adoc[Access the Developer Portal] - As an administrator, you can view the resources and methods of an API, and access other details, such as publish date and mocking service, from Anypoint Exchange (Exchange). You can view the API in an asset portal (private) or a public portal.
 . Modify an API instance when you no longer need the instance or when you need to update it:
-** xref:edit-api-endpoint-task.adoc[Edit an API Instance Endpoint] - Edit the API instance's endpoint to update its base path, port, TLS context, and more.
+** xref:edit-api-endpoint-task.adoc[Edit an API Instance] - Edit the API instance's configuration settings to update its base path, port, TLS context, and more.
 ** xref:deprecate-api-latest-task.adoc[Deprecate an API Instance] - While transitioning consumers of your API to an updated instance, you can prevent developers from signing up for access to your old API instance. 
 ** xref:delete-api-task.adoc[Delete an API Instance] - You can delete an API instance and its version if you no longer need to manage it from API Manager. 
 ** xref:manage-versions-instances-concept.adoc[Manage API Versions] - After you create an API in Anypoint Platform, you configure the version details for the API and then publish it to Anypoint Exchange (Exchange). The API version resides in Exchange, and not in API Manager. However, you then manage this API version from API Manager.