Merge pull request #106715 from mikebudzynski/apim-portal-revise

APIM: revise portal docs

Author: PRMerger12

articles/api-management/api-management-howto-developer-portal-customize.md

@@ -11,7 +11,7 @@ ms.service: api-management
 ms.workload: mobile
 ms.tgt_pltfrm: na
 ms.topic: article
-ms.date: 11/22/2019
+ms.date: 03/05/2020
 ms.author: apimpm
 ---
 
@@ -122,6 +122,10 @@ To make your portal and its latest changes available to visitors, you need to pu
 
 After you publish the portal, you can access it at the same URL as the administrative panel, for example `https://contoso-api.developer.azure-api.net`. View it in a separate browser session (incognito / private browsing mode) as an external visitor.
 
+## Apply the CORS policy on APIs
+
+You need to enable CORS (cross-origin resource sharing) on your APIs to let the visitors of your portal test the APIs through the built-in interactive console. Refer to [this documentation article](api-management-howto-developer-portal.md#cors) for more details.
+
 ## Next steps
 
 Learn more about the developer portal:

articles/api-management/api-management-howto-developer-portal.md

@@ -12,7 +12,7 @@ ms.service: api-management
 ms.workload: mobile
 ms.tgt_pltfrm: na
 ms.topic: article
-ms.date: 11/22/2019
+ms.date: 03/05/2020
 ms.author: apimpm
 ---
 
@@ -22,10 +22,6 @@ Developer portal is an automatically generated, fully customizable website with
 
 This article describes the differences between self-hosted and managed versions of the developer portal in API Management. It also explains its architecture and provides answers to frequently asked questions.
 
-> [!WARNING]
->
-> [Learn how to migrate from the preview version to the generally available version](#preview-to-ga) of the developer portal.
-
 ![API Management developer portal](media/api-management-howto-developer-portal/cover.png)
 
 [!INCLUDE [premium-dev-standard-basic.md](../../includes/api-management-availability-premium-dev-standard-basic.md)]
@@ -35,7 +31,7 @@ This article describes the differences between self-hosted and managed versions
 You can build your developer portal in two ways:
 
 - **Managed version** - by editing and customizing the portal, which is built into your API Management instance and is accessible through the URL `<your-api-management-instance-name>.developer.azure-api.net`. Refer to [this documentation article](api-management-howto-developer-portal-customize.md) to learn how to access and customize the managed portal.
-- **Self-hosted version** - by deploying and self-hosting your portal outside of an API Management instance. This approach allows you to edit the portal's codebase and extend the provided core functionality. You also need to upgrade the portal to the latest version yourself. For details and instructions, refer to the [GitHub repository with the source code of the portal][1] and [the tutorial on implementing a widget][3]. The [tutorial for the managed version](api-management-howto-developer-portal-customize.md) walks through the portal's administrative panel, which is also featured in the self-hosted version.
+- **Self-hosted version** - by deploying and self-hosting your portal outside of an API Management instance. This approach allows you to edit the portal's codebase and extend the provided core functionality - for example, implement custom widgets for integrations with third party systems. In this scenario, you are the portal's maintainer and you are responsible for upgrading the portal to the latest version. For details and instructions, refer to the [GitHub repository with the source code of the portal][1] and [the tutorial on implementing a widget][3]. The [tutorial for the managed version](api-management-howto-developer-portal-customize.md) walks through the portal's administrative panel, which is common for the managed and the self-hosted versions.
 
 ## Portal architectural concepts
 
@@ -66,7 +62,7 @@ The portal is based on an adapted fork of the [Paperbits framework](https://pape
 
 ## <a name="faq"></a> Frequently asked questions
 
-In this section, we answer common questions about the new developer portal, which are of general nature. For questions specific to the self-hosted version, refer to [the wiki section of the GitHub repository](https://github.com/Azure/api-management-developer-portal/wiki).
+In this section, we answer common questions about the developer portal, which are of general nature. For questions specific to the self-hosted version, refer to [the wiki section of the GitHub repository](https://github.com/Azure/api-management-developer-portal/wiki).
 
 ### <a id="preview-to-ga"/> How can I migrate from the preview version of the portal?
 
@@ -82,13 +78,13 @@ If you don't want to reset the content of the portal, you may consider using new
 
 If your portal was provisioned after the general availability announcement, it should already feature the new default content. No action is required from your side.
 
-### How can I migrate from the old developer portal to the new developer portal?
+### How can I migrate from the old developer portal to the developer portal?
 
 Portals are incompatible and you need to migrate the content manually.
 
-### Does the new portal have all the features of the old portal?
+### Does the portal have all the features of the old portal?
 
-The new developer portal doesn't support *Applications* and *Issues*. If you have used *Issues* in the old portal and need them in the new one, post a comment in [a dedicated GitHub issue](https://github.com/Azure/api-management-developer-portal/issues/122).
+The developer portal no longer supports *Applications* and *Issues*.
 
 Authentication with OAuth in the interactive developer console is not yet supported. You can track the progress through [the GitHub issue](https://github.com/Azure/api-management-developer-portal/issues/208).
 
@@ -100,24 +96,26 @@ Deprecation of the legacy portals will be announced separately. If you have ques
 
 ### Functionality I need isn't supported in the portal
 
-Use the self-hosted version and [implement your own widget][3].
+You can open a [feature request](https://aka.ms/apimwish) or [implement the missing functionality yourself][3]. If you implement the functionality yourself, you can either self-host the developer portal or open a pull request on GitHub to include the changes in the managed version.
 
 ### How can I automate portal deployments?
 
 You can programmatically access and manage the developer portal's content through the REST API, regardless if you're using a managed or a self-hosted version.
 
-The API is documented in [the GitHub repository's wiki section][2]. It can also be used for automating migrations of portal content between environments - for example from a test environment to the production environment. You can learn more about this process [in this documentation article](https://aka.ms/apimdocs/migrateportal) on GitHub.
+The API is documented in [the GitHub repository's wiki section][2]. It can be used for automating migrations of portal content between environments - for example, from a test environment to the production environment. You can learn more about this process [in this documentation article](https://aka.ms/apimdocs/migrateportal) on GitHub.
 
 ### Does the portal support Azure Resource Manager templates and/or is it compatible with API Management DevOps Resource Kit?
 
 No.
 
-### Do I need to enable additional VNet connectivity for the new managed portal dependencies?
+### Do I need to enable additional VNet connectivity for the managed portal dependencies?
 
 In most cases - no.
 
 If your API Management service is in an internal VNet, your developer portal is only accessible from within the network. The management endpoint's host name must resolve to the internal VIP of the service from the machine you use to access the portal's administrative interface. Make sure the management endpoint is registered in the DNS. In case of misconfiguration, you will see an error: `Unable to start the portal. See if settings are specified correctly in the configuration (...)`.
 
+If your API Management service is in an internal VNet and you're accessing it through Application Gateway from the Internet, make sure to enable connectivity to the developer portal and the management endpoints of API Management.
+
 ### I have assigned a custom API Management domain and the published portal doesn't work
 
 After you update the domain, you need to [republish the portal](api-management-howto-developer-portal-customize.md#publish) for the changes to take effect.
@@ -134,7 +132,7 @@ After you set up delegation, you need to [republish the portal](api-management-h
 
 Most configuration changes (for example, VNet, sign-in and product terms) require [republishing the portal](api-management-howto-developer-portal-customize.md#publish).
 
-### I'm getting a CORS error when using the interactive console
+### <a name="cors"></a> I'm getting a CORS error when using the interactive console
 
 The interactive console makes a client-side API request from the browser. You can resolve the CORS problem by adding [a CORS policy](api-management-cross-domain-policies.md#CORS) on your API(s). You can specify all the parameters manually or use wildcard `*` values. For example:
 
@@ -166,7 +164,7 @@ The interactive console makes a client-side API request from the browser. You ca
 > 
 > If you apply the CORS policy in the Product scope, instead of the API(s) scope, and your API uses subscription key authentication through a header, your console won't work.
 >
-> The browser automatically issues an OPTIONS HTTP request, which doesn’t contain a header with the subscription key. Because of the missing subscription key, API Management can't associate the OPTIONS call with a Product, so it can’t apply the CORS policy.
+> The browser automatically issues an OPTIONS HTTP request, which doesn't contain a header with the subscription key. Because of the missing subscription key, API Management can't associate the OPTIONS call with a Product, so it can't apply the CORS policy.
 >
 > As a workaround you can pass the subscription key in a query parameter.