Merge pull request #537 from mulesoft/W-13734629-apig-apim-internal-doc-br-bsj

W-13750485 APIM <> APIG

Author: glenn-rodgers-sf

modules/ROOT/nav.adoc

@@ -16,6 +16,7 @@
  ** xref:delete-api-task.adoc[Delete an API Instance]
  ** xref:manage-versions-instances-concept.adoc[Manage API Instance Versions]
  ** xref:configure-multiple-credential-providers.adoc[Configure Multiple Client Provider]
+ ** xref:govern-api-instances.adoc[Govern API Instances]
 * xref:api-groups-landing-page.adoc[Manage API Groups]
  ** xref:api-groups-creating-groups.adoc[Create API Groups]
  ** xref:api-groups-modifying-groups.adoc[Modify API Groups]

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

@@ -98,7 +98,10 @@ See xref:runtime-fabric::proxy-deploy-runtime-fabric.adoc[Deploying API Proxies
 * Click **Select API from Exchange** if you have an API shared with you through Exchange that you want to manage.
 [arabic]
 .. Click the API from the list under **Select API**. You can search for a specific API if needed.
-.. Update the *Asset type*, *API version*, and *Asset version* if needed.
+.. Update the *Asset type*, *API version*, and *Asset version* if you are not using the latest version.
++
+For more information about versions in Exchange, see xref:exchange::asset-versions.adoc[].
+.. If you chose a *RAML/OAS* asset type, view the *Conformance Status* of the API to ensure the API is conformant. If the *Conformance Status* is nonconformant, after deployment, view the *Governance Report* to find and fix the conformance issues. For more information about the *Governance Report*, see xref:govern-api-instances.adoc[].
 
 * Click **Create new API**:
 [arabic]
@@ -114,7 +117,10 @@ See xref:runtime-fabric::proxy-deploy-runtime-fabric.adoc[Deploying API Proxies
 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.
 
-.. Optionally, click *Advanced* to edit the *AssetId* and the *Version*.
+.. Update the *Asset type*, *API version*, and *Asset version* if you are not using the latest version.
++
+For more information about versions in Exchange, see xref:exchange::asset-versions.adoc[].
+.. If you chose a *RAML/OAS* asset type, view the *Conformance Status* of the API to ensure the API is conformant. If the *Conformance Status* is nonconformant, after deployment, view the *Governance Report* to find and fix the conformance issues. For more information about the *Governance Report*, see xref:govern-api-instances.adoc[].
 . Click *Next*.
 //end::asset-type-options-flex[]
 
@@ -131,7 +137,10 @@ Upload either a RAML or OAS file for your REST API. Versions 2.0.0 and later are
 Upload a WSDL file for your SOAP API or add the link to the file. +
 This option is not available for Flex Gateway runtime at this time.
 
-.. Optionally, click *Advanced* to edit the *AssetId* and the *Version*.
+.. Update the *Asset type*, *API version*, and *Asset version* if you are not using the latest version.
++
+For more information about versions in Exchange, see xref:exchange::asset-versions.adoc[].
+.. If you chose a *RAML/OAS* asset type, view the *Conformance Status* of the API to ensure the API is conformant. If the *Conformance Status* is nonconformant, after deployment, view the *Governance Report* to find and fix the conformance issues. For more information about the *Governance Report*, see xref:govern-api-instances.adoc[].
 . Click *Next*.
 //end::asset-type-options[]
 
@@ -142,15 +151,18 @@ This option is not available for Flex Gateway runtime at this time.
 +
 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.
 
-.. Optionally, click *Advanced* to edit the *AssetId* and the *Version*.
+.. Update the *Asset type*, *API version*, and *Asset version* if you are not using the latest version.
++
+For more information about versions in Exchange, see xref:exchange::asset-versions.adoc[].
+.. View the *Conformance Status* of the API to ensure the API is conformant. If the *Conformance Status* is nonconformant, after deployment, view the *Governance Report* to find and fix the conformance issues. For more information about the *Governance Report*, see xref:govern-api-instances.adoc[]
 . Click *Next*.
 //end::raml-oas[]
 
 // asset type options for SOAP Proxies
 //tag::soap[]
 .. Select **SOAP API** as the **Asset type**.
 .. Select either *Upload a WSDL* or *Use an external link* as the method.
-.. Optionally, click *Advanced* to edit the *AssetId* and the *Version*.
+.. Update the *Asset type*, *API version*, and *Asset version* if needed.
 . Click *Next*.
 //end::soap[]
 

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

@@ -28,4 +28,6 @@ To manage API instances in 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.
 . Explore advanced use cases for API instances:
 +
-xref:configure-multiple-credential-providers.adoc[Configure Multiple Client Providers] - You can use multiple client providers, such as OpenAM and PingFederate, to help you enforce security and regulations in your business organization. These client providers enable you to secure your operational data, including client credentials and access tokens.
+* xref:configure-multiple-credential-providers.adoc[Configure Multiple Client Providers] - You can use multiple client providers, such as OpenAM and PingFederate, to help you enforce security and regulations in your business organization. These client providers enable you to secure your operational data, including client credentials and access tokens.
++
+* xref:govern-api-instances.adoc[Govern API Instances] - You can govern API instances using Anypoint API Governance. View the governance validation report for governed instances to identify conformance issues and take action to fix them. 

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

@@ -0,0 +1,37 @@
+= Governing API Instances
+ifndef::env-site,env-github[]
+include::_attributes.adoc[]
+endif::[]
+
+
+API Manager is closely integrated with xref:api-governance::index.adoc[Anypoint API Governance] to govern aspects of API instances with governance rulesets. Applying a governance ruleset to your API ensures that every instance of that API conforms to standards such as what policies are applied and if a TLS context is required.  
+
+To govern an API instance:
+
+. <<apply-a-ruleset>>
+. <<view-api-manager>>
+
+[[apply-a-ruleset]]
+== Apply a Governance Ruleset
+
+To govern API instances, you must apply a governance ruleset to your desired API. To apply a governance ruleset, see xref:api-governance::create-profiles.adoc[].
+
+To create custom rulesets that enforce your own API management standards, see xref:api-governance::create-custom-rulesets.adoc[].
+
+[[view-api-manager]]
+
+== View and Fix Instance Conformance Issues in API Manager
+
+To view the conformance status of an API instance:
+
+. Navigate to *Anypoint Platform* > *API Manager*. 
+. Click the name of the API instance for which you want to view the conformance status.
++
+*Instance Conformance* appears in the *API Summary* pane.
+. If the instance is not conformant, select the *Governance Report* page to view nonconformance details for each ruleset.
+. Click *View details* for each ruleset for more information about the conformance issues.
+
+
+== See Also
+
+* xref:api-governance::fix-instance-conformance-issues.adoc[]

modules/ROOT/pages/latest-overview-concept.adoc

@@ -14,10 +14,11 @@ Anypoint API Manager (API Manager) is a component of Anypoint Platform that enab
 
 API Manager is tightly integrated with the following tools:
 
-* xref:design-center::index.adoc[Anypoint Design Center (Design Center)], for specifying the structure of the API
-* xref:exchange::index.adoc[Anypoint Exchange (Exchange)], for storing and publishing API assets
-* xref:studio::index.adoc[Anypoint Studio (Studio)], for implementing the API
-* xref:runtime-manager::index.adoc[Anypoint Runtime Manager (Runtime Manager)], to deploy, manage, and monitor the API (or proxy)
+* xref:design-center::index.adoc[Design Center]: To specify the structure of the API
+* xref:exchange::index.adoc[Exchange]: To store and publish API assets
+* xref:studio::index.adoc[Studio]: To implement the API
+* xref:runtime-manager::index.adoc[Runtime Manager]: To deploy, manage, and monitor API instances
+* xref:api-governance::index.adoc[API Governance]: To govern API instances
 
 Before using API Manager, familiarize yourself with the user interface and the tasks you can perform therein.
 
@@ -63,9 +64,13 @@ The endpoint must have a tracking registration status of *Active* for governance
 
 . The name of each API. Clicking the API name navigates you to the API *Settings* view, where you manage the following:
 +
+** *API Summary*
++
+For details, see xref:api-instance-landing-page.adoc[].
++
 ** *Alerts*
 +
-For details, see xref:using-api-alerts.adoc[Reviewing Alerts Concepts].
+For details, see xref:using-api-alerts.adoc[].
 ** *Contracts*
 +
 For details, see xref:api-contracts-landing-page.adoc[Client Applications and Contracts].
@@ -74,7 +79,13 @@ For details, see xref:api-contracts-landing-page.adoc[Client Applications and Co
 For details, see xref:policies-landing-page.adoc[Policies].
 ** *SLA Tiers*
 +
-For details, see xref:defining-sla-tiers.adoc[Reviewing SLA Tiers Concepts].
+For details, see xref:defining-sla-tiers.adoc[].
+** *Settings*
++
+For details, see xref:edit-api-endpoint-task.adoc[].
+** *Governance Report*
++
+For details, see xref:instance-governance.adoc[].
 
 . The percentage of API requests that resulted in errors (in the past 24 hours).
 +
@@ -90,6 +101,40 @@ see xref:api-contracts-landing-page.adoc[Client Applications and Contracts].
 
 == API Manager Components, Concepts, and Features
 
+=== API Instances
+
+An API instance describes a configuration of an API that is deployed on one of the following runtimes: Flex Gateway, Mule Gateway, or Service Mesh. API instances are managed by API Manager after they are created by using the add, promote, or import options. API instances remain under management until they are deleted.
+
+The API Summary shows key information about a deployed API instance:
+
+image::api-instance-summary.png[API Summary page]
+
+For details, see xref:api-instance-landing-page.adoc[API Instance].
+
+=== API Alerts
+
+An _API alert_ (different from a Runtime Manager alert) is an alarm that flags one of the following:
+
+* The API request violates a policy.
+* Requests received by the API exceed a given number within a specified period of time.
+* The API returns a specified HTTP error code.
+* The API response time exceeds a specified timeout value.
+
+API Manager triggers alerts when states change from desirable to undesirable or vice versa. When an alert is triggered, API Manager sends an email notification to you and to anyone else you specify in the configuration.
+
+For details, see xref:using-api-alerts.adoc[Reviewing Alerts Concepts].
+
+=== Contracts
+
+Contracts define how client applications consume APIs. A client application requests access in Exchange. Either the owner of the API instance approves the request in API Manager or the approval is automatic, depending on configuration. 
+
+Contracts are enforced with either of the following:
+
+* SLA enforcement policies
+* Client enforcement policies
+
+For details about enforcement policies, see xref:api-contracts-landing-page.adoc[Client Applications and Contracts].
+
 === Policies
 
 Policies enable you to enforce regulations to help manage security, control traffic, and improve adaptability of your APIs. For example, a policy can control authentication, access, allotted consumption, and service level access (SLA).
@@ -107,35 +152,32 @@ _Service Level Access (SLA) tiers_ are categories of user access that you define
 
 For details, see xref:defining-sla-tiers.adoc[Reviewing SLA Tiers Concepts].
 
-=== Client Providers (Identity Providers)
+=== Settings
 
-You use client providers to enforce security and regulations in your business organization. Client providers authorize client applications. 
+When adding an API instance, you configure the API instance settings to set parameters such as the runtime and upstream and downstream URIs.
 
-For details about using client providers, see xref:configure-multiple-credential-providers.adoc[Configure Multiple Client Providers for Client Management].
+To add an API instance, see xref:add-api-instances.adoc[].
 
-=== Contracts
+After you create the API instance, you can edit the configuration settings from Settings.
 
-Contracts define how client applications consume APIs. A client application requests access in Exchange. Either the owner of the API instance approves the request in API Manager or the approval is automatic, depending on configuration. 
+To edit an API instance, see xref:edit-api-endpoint-task.adoc[Edit an API Instance].
 
-Contracts are enforced with either of the following:
+=== Governance Report
 
-* SLA enforcement policies
-* Client enforcement policies
+API Governance is integrated with API Manager to identify the conformance status of your API instances.
 
-For details about enforcement policies, see xref:api-contracts-landing-page.adoc[Client Applications and Contracts].
+API Governance tests API instances against rulesets to determine conformance issues such as missing policies and missing TLS contexts.
 
-=== API Alerts
+You can view the governance validation report details to get the information you need to fix conformance issues. The validation report is available both in API Manager on the Governance Report page and in API Governance.
 
-An _API alert_ (different from a Runtime Manager alert) is an alarm that flags one of the following:
+To learn more about governing your API instances, see xref:govern-api-instances.adoc[Govern API Instances].
+ 
 
-* The API request violates a policy.
-* Requests received by the API exceed a given number within a specified period of time.
-* The API returns a specified HTTP error code.
-* The API response time exceeds a specified timeout value.
+=== Client Providers (Identity Providers)
 
-API Manager triggers alerts when states change from desirable to undesirable or vice versa. When an alert is triggered, API Manager sends an email notification to you and to anyone else you specify in the configuration.
+You use client providers to enforce security and regulations in your business organization. Client providers authorize client applications. 
 
-For details, see xref:using-api-alerts.adoc[Reviewing Alerts Concepts].
+For details about using client providers, see xref:configure-multiple-credential-providers.adoc[Configure Multiple Client Providers for Client Management].
 
 === API Assets
 
@@ -164,16 +206,6 @@ An _API group_ is a collection of API instances that act as a single unit, so th
 
 For details, see xref:api-groups-landing-page.adoc[API Groups].
 
-=== API Instances
-
-An API instance describes a configuration of an API that is deployed on one of the following runtimes: Flex Gateway, Mule Gateway, or Service Mesh. API instances are managed by API Manager after they are created using add, promote, or import options. API instances remain under management until they are deleted.
-
-The API Summary shows key information about a deployed API instance:
-
-image::api-instance-summary.png[API Summary page]
-
-For details, see xref:api-instance-landing-page.adoc[API Instance].
-
 === Autodiscovery Schemes
 
 Through autodiscovery schemes, API Manager can track the API throughout the life cycle as you modify, version, deploy, govern, and publish it.

modules/ROOT/pages/manage-versions-instances-concept.adoc

@@ -3,16 +3,16 @@ ifndef::env-site,env-github[]
 include::_attributes.adoc[]
 endif::[]
 
-In Anypoint Exchange (Exchange), you can add, delete, and deprecate API versions, also known as _Exchange assets_. An API version in Exchange can have its own RAML file, API portal, and URL. For more information on how to manage API versions in Exchange, see xref:exchange::manage-versions.adoc[Manage Versions].
+After you publish new version details for an API definition to Exchange, you must update the *Asset version* of your deployed API instances in API Manager to reflect the changes.
 
-After you publish new version details for an API definition to Exchange, you must change the version of your API instance in API Manager if you want the instance to reflect the latest version. For more information on API instances, see xref:api-instance-landing-page.adoc[API Instance].
+For more information about versions in Exchange, see xref:exchange::asset-versions.adoc[].
 
 To change the asset version of an API instance:
 
-. Navigate to *Anypoint Platform* > *API Manager*.
-. In *API Administration*, click the name of the API instance whose version you want to manage.
+. Navigate to *Anypoint Platform* > *API Manager*. 
+. In *API Administration*, click the name of the API instance for which you want to change the version.
 . Select *Actions* > *Change API specification*.
-. In *Asset version*, Select *latest*. 
+. In *Asset version*, select your desired version. 
 . Click *Change*.
 
 == See Also