Merge pull request #17 from craigshoemaker/anthony/apis

[Static Web Apps] Bring your own backend edits
changeworld · Jun 14, 2022 · 9c8521f · 9c8521f
2 parents 1c6f10f + b8b2693
commit 9c8521f
Show file tree

Hide file tree

Showing 5 changed files with 62 additions and 51 deletions.
diff --git a/articles/static-web-apps/apis-api-management.md b/articles/static-web-apps/apis-api-management.md
@@ -5,24 +5,22 @@ services: static-web-apps
 author: craigshoemaker
 ms.service: static-web-apps
 ms.topic:  conceptual
-ms.date: 06/02/2022
+ms.date: 06/14/2022
 ms.author: cshoe
 ---
 
 # API support in Azure Static Web Apps with Azure API Management
 
-[!INCLUDE [APIs overview](../../includes/static-web-apps-apis-overview.md)]
-
-## Overview
+[Azure API Management](../api-management/api-management-key-concepts.md) is a service that allows you to create a modern API gateway for existing back end services.
 
-[Azure API Management](../api-management/api-management-key-concepts.md) is a service that allows you to create a modern API gateway for existing back-end services.
-
-When you link your Azure API Management service to your static web app, any requests to your static web app with a route that starts with `/api/` are proxied to the same route in the Azure API Management service.
+When you link your Azure API Management service to your static web app, any requests to your static web app with a route that starts with `/api` are proxied to the same route in the Azure API Management service.
 
 An Azure API Management service can be linked to multiple static web apps at the same time. An API Management product is created for each linked static web app. Any APIs added to the product is available to the associated static web app.
 
 All Azure API Management pricing tiers are available for use with Azure Static Web Apps.
 
+[!INCLUDE [APIs overview](../../includes/static-web-apps-apis-overview.md)]
+
 > [!NOTE]
 > Currently, you cannot link an API Management service to a Static Web Apps [pull request environment](review-publish-pull-requests.md).
 
@@ -44,18 +42,27 @@ To link an Azure API Management service as the API backend for a static web app,
 
 1. Select **Link**.
 
-When the linking process is complete, requests to routes beginning with `/api/` are proxied to your Azure API Management service. However, no APIs are exposed by default. See [Manage access to APIs](#manage-access-to-apis) to configure an API Management product to allow the APIs you want to use.
+When the linking process is complete, requests to routes beginning with `/api` are proxied to your Azure API Management service. However, no APIs are exposed by default. See [Manage access to APIs](#manage-access-to-apis) to configure an API Management product to allow the APIs you want to use.
 
 ### Manage access to APIs
 
 Azure API Management has a *products* feature that defines how APIs are surfaced. As part of the linking process, your API Management service is configured with a product named `Azure Static Web Apps - <STATIC_WEB_APP_AUTO_GENERATED_HOSTNAME> (Linked)`.
 
-Because no APIs are associated with the new API Management product, accessing a `/api/` route in your static web app returns a `{ "statusCode": 401, "message": "Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription." }` error from API Management. To make APIs available to your linked static web app, [add them to the product](../api-management/api-management-howto-add-products.md#add-apis-to-a-product).
+Because no APIs are associated with the new API Management product, accessing a `/api` route in your static web app returns the following error from API management.
+
+```json
+{
+  "statusCode": 401,
+  "message": "Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription."
+}
+```
+
+To make APIs available to your linked static web app, [add them to the product](../api-management/api-management-howto-add-products.md#add-apis-to-a-product).
 
 The linking process also automatically applies the following configuration to your API Management service:
 
 * The product associated with the linked static web app is configured to require a subscription.
-* An API Management subscription named `Generated for Static Web Apps resource with default hostname: <STATIC_WEB_APP_AUTO_GENERATED_HOSTNAME>` is created. It's scoped to the product with the same name.
+* An API Management subscription named `Generated for Static Web Apps resource with default hostname: <STATIC_WEB_APP_AUTO_GENERATED_HOSTNAME>` is created and scoped to the product with the same name.
 * An inbound *validate-jwt* policy is added to the product to allow only requests that contain a valid access token from the linked static web app.
 * The linked static web app is configured to include the subscription's primary key and a valid access token when proxying requests to the API Management service.
 

diff --git a/articles/static-web-apps/apis-app-service.md b/articles/static-web-apps/apis-app-service.md
@@ -5,24 +5,22 @@ services: static-web-apps
 author: craigshoemaker
 ms.service: static-web-apps
 ms.topic:  conceptual
-ms.date: 06/02/2022
+ms.date: 06/14/2022
 ms.author: cshoe
 ---
 
 # API support in Azure Static Web Apps with Azure App Service
 
-[!INCLUDE [APIs overview](../../includes/static-web-apps-apis-overview.md)]
-
-## Overview
-
-[Azure App Service](../app-service/overview.md) is a managed platform for hosting web applications that execute code on servers. It supports many runtimes and frameworks including Node.js, ASP.NET Core, PHP, Java, and Python.
+[Azure App Service](../app-service/overview.md) is a managed platform for hosting web applications that execute code on servers. Azure App Service supports many runtimes and frameworks including Node.js, ASP.NET Core, PHP, Java, and Python.
 
-When you link your Azure App Service web app to your static web app, any requests to your static web app with a route that starts with `/api/` are proxied to the same route on the Azure App Service app.
+When you link your Azure App Service web app to your static web app, any requests to your static web app with a route that starts with `/api` are proxied to the same route on the Azure App Service app.
 
-By default, when an App Service app is linked to a static web app, the App Service app only accepts requests that are proxied through the linked static web app. An Azure App Service app can be linked to a single static web app at a time.
+By default, when an App Service app is linked to a static web app, the App Service app only accepts requests that are proxied through the linked static web app. An Azure App Service app can only be linked to a single static web app at a time.
 
 All Azure App Service hosting plans are available for use with Azure Static Web Apps.
 
+[!INCLUDE [APIs overview](../../includes/static-web-apps-apis-overview.md)]
+
 > [!NOTE]
 > You cannot link a web app to a Static Web Apps [pull request environment](review-publish-pull-requests.md).
 
@@ -44,7 +42,7 @@ To link a web app as the API backend for a static web app, follow these steps:
 
 1. Select **Link**.
 
-When the linking process is complete, requests to routes beginning with `/api/` are proxied to the linked App Service app.
+When the linking process is complete, requests to routes beginning with `/api` are proxied to the linked App Service app.
 
 ### Manage access to Azure App Service
 
@@ -62,7 +60,7 @@ To unlink a web app from a static web app, follow these steps:
 
 1. Select **Unlink**.
 
-When the unlinking process is complete, requests to routes beginning with `/api/` are no longer proxied to your App Service app.
+When the unlinking process is complete, requests to routes beginning with `/api` are no longer proxied to your App Service app.
 
 > [!NOTE]
 > To prevent accidentally exposing your App Service app to anonymous traffic, the identity provider created by the linking process is not automatically deleted. You can delete the identity provider named *Azure Static Web Apps (Linked)* from the App Service app's authentication settings.

diff --git a/articles/static-web-apps/apis-container-apps.md b/articles/static-web-apps/apis-container-apps.md
@@ -5,22 +5,20 @@ services: static-web-apps
 author: craigshoemaker
 ms.service: static-web-apps
 ms.topic:  conceptual
-ms.date: 06/02/2022
+ms.date: 06/14/2022
 ms.author: cshoe
 ---
 
 # API support in Azure Static Web Apps with Azure Container Apps
 
-[!INCLUDE [APIs overview](../../includes/static-web-apps-apis-overview.md)]
-
-## Overview
-
 [Azure Container Apps](../container-apps/overview.md) is a managed platform for hosting serverless containers and microservices.
 
-When you link your container app to your static web app, any requests to your static web app with a route that starts with `/api/` are proxied to the same route on the container app.
+When you link your container app to your static web app, any requests to your static web app with a route that starts with `/api` are proxied to the same route on the container app.
 
 By default, when a container app is linked to a static web app, the container app only accepts requests that are proxied through the linked static web app. A container app can be linked to a single static web app at a time.
 
+[!INCLUDE [APIs overview](../../includes/static-web-apps-apis-overview.md)]
+
 > [!NOTE]
 > You cannot link a container app to a Static Web Apps [pull request environment](review-publish-pull-requests.md).
 
@@ -42,7 +40,7 @@ To link a web app as the API backend for a static web app, follow these steps:
 
 1. Select **Link**.
 
-When the linking process is complete, requests to routes beginning with `/api/` are proxied to the linked container app.
+When the linking process is complete, requests to routes beginning with `/api` are proxied to the linked container app.
 
 ### Manage access to the container app
 
@@ -60,7 +58,7 @@ To unlink a container app from a static web app, follow these steps:
 
 1. Select **Unlink**.
 
-When the unlinking process is complete, requests to routes beginning with `/api/` are no longer proxied to your container app.
+When the unlinking process is complete, requests to routes beginning with `/api` are no longer proxied to your container app.
 
 > [!NOTE]
 > To prevent accidentally exposing your container app to anonymous traffic, the identity provider created by the linking process is not automatically deleted. You can delete the identity provider named *Azure Static Web Apps (Linked)* from the container app's authentication settings.

diff --git a/articles/static-web-apps/apis.md b/articles/static-web-apps/apis.md
@@ -5,13 +5,31 @@ services: static-web-apps
 author: craigshoemaker
 ms.service: static-web-apps
 ms.topic:  conceptual
-ms.date: 06/02/2022
+ms.date: 06/14/2022
 ms.author: cshoe
 ---
 
 # API support in Azure Static Web Apps with Azure Functions
 
-[!INCLUDE [APIs overview](../../includes/static-web-apps-apis-overview.md)]
+Front end web applications often call back end APIs for data and services. By default, Azure Static Web Apps provides built-in serverless API endpoints via [Azure Functions](../articles/static-web-apps/apis.md).
+
+Key features of built-in APIs include:
+
+- **Integrated security** with direct access to user [authentication and role-based authorization](../articles/static-web-apps/user-information.md) data.
+
+- **Seamless routing** that makes the `/api` route available to the front-end web app without requiring custom CORS rules.
+
+Other API options include the following Azure services:
+
+* [Azure Functions](apis.md)
+* [Azure API Management](apis-api-management.md)
+* [Azure App Service](apis-app-service.md)
+* [Azure Container Apps](apis-container-apps.md)
+
+Each static web app environment can only be configured with one type of backend API at a time.
+
+> [!NOTE]
+> Backend APIs integration with other Azure services is only available in the Azure Static Web Apps Standard plan. Built-in, managed Azure Functions APIs are available in all Azure Static Web Apps plans.
 
 Azure Functions APIs in Static Web Apps are supported by two possible configurations depending on the [hosting plan](plans.md#features):
 
@@ -22,12 +40,12 @@ Azure Functions APIs in Static Web Apps are supported by two possible configurat
 The following table contrasts the differences between using managed and existing functions.
 
 | Feature | Managed Functions | Bring your own Functions |
-| --- | --- | --- |
-| Access to Azure Functions [triggers](../azure-functions/functions-triggers-bindings.md#supported-bindings) | Http only | All |
+|---|---|---|
+| Access to Azure Functions [triggers](../azure-functions/functions-triggers-bindings.md#supported-bindings) | HTTP only | All |
 | Supported Azure Functions [runtimes](../azure-functions/supported-languages.md#languages-by-runtime-version)<sup>1</sup> | Node.js 12<br>Node.js 14<br>Node.js 16<br>.NET Core 3.1<br>.NET 6.0<br>Python 3.8<br>Python 3.9 | All |
 | Supported Azure Functions [hosting plans](../azure-functions/functions-scale.md) | Consumption | Consumption<br>Premium<br>Dedicated |
 | [Integrated security](user-information.md) with direct access to user authentication and role-based authorization data | ✔ | ✔ |
-| [Routing integration](./configuration.md?#routes) that makes the _api_ route available to the web app securely without requiring custom CORS rules. | ✔ | ✔ |
+| [Routing integration](./configuration.md?#routes) that makes the `/api` route available to the web app securely without requiring custom CORS rules. | ✔ | ✔ |
 | [Durable Functions](../azure-functions/durable/durable-functions-overview.md) programming model | ✕ | ✔ |
 | [Managed identity](../app-service/overview-managed-identity.md) | ✕ | ✔ |
 | [Azure App Service Authentication and Authorization](../app-service/configure-authentication-provider-aad.md) token management | ✕ | ✔ |
@@ -38,27 +56,27 @@ The following table contrasts the differences between using managed and existing
 
 ## Configuration
 
-API endpoints are available to the web app through the _api_ route.
+API endpoints are available to the web app through the `api` route.
 
 | Managed functions | Bring your own functions |
-| --- | --- |
-| While the _api_ route is fixed, you have control over the source code folder location of the managed functions app. You can change this location by [editing the workflow YAML file](build-configuration.md) located in your repository's _.github/workflows_ folder. | Requests to the _api_ route are sent to your existing Azure Functions app. |
+|---|---|
+| While the `/api` route is fixed, you have control over the source code folder location of the managed functions app. You can change this location by [editing the workflow YAML file](build-configuration.md) located in your repository's _.github/workflows_ folder. | Requests to the `/api` route are sent to your existing Azure Functions app. |
 
 ## Troubleshooting and logs
 
 Logs are only available if you add [Application Insights](monitor.md).
 
 | Managed functions | Bring your own functions |
-| --- | --- |
+|---|---|
 | Turn on logging by enabling Application Insights on your static web app. | Turn on logging by enabling Application Insights on your Azure Functions app. |
 
 ## Constraints
 
-- The API route prefix must be _api_.
+- The API route prefix must be `/api`.
 - Route rules for API functions only support [redirects](configuration.md#defining-routes) and [securing routes with roles](configuration.md#securing-routes-with-roles).
 
 | Managed functions | Bring your own functions |
-| --- | --- |
+|---|---|
 | <ul><li>Triggers are limited to [HTTP](../azure-functions/functions-bindings-http-webhook.md).</li><li>The Azure Functions app must either be in Node.js 12, Node.js 14, Node.js 16, .NET Core 3.1, .NET 6.0, Python 3.8, or Python 3.9.</li><li>Some application settings are managed by the service, therefore the following prefixes are reserved by the runtime:<ul><li>*APPSETTING\_, AZUREBLOBSTORAGE\_, AZUREFILESSTORAGE\_, AZURE_FUNCTION\_, CONTAINER\_, DIAGNOSTICS\_, DOCKER\_, FUNCTIONS\_, IDENTITY\_, MACHINEKEY\_, MAINSITE\_, MSDEPLOY\_, SCMSITE\_, SCM\_, WEBSITES\_, WEBSITE\_, WEBSOCKET\_, AzureWeb*</li></ul></li><li>Some application tags are internally used by the service. Therefore, the following tags are reserved:<ul><li> *AccountId, EnvironmentId, FunctionAppId*.</li></ul></li></ul> | <ul><li>You are responsible to manage the Functions app deployment.</li></ul> |
 
 ## Next steps

diff --git a/includes/static-web-apps-apis-overview.md b/includes/static-web-apps-apis-overview.md
@@ -2,23 +2,13 @@
 author: craigshoemaker
 ms.service: static-web-apps
 ms.topic: include
-ms.date: 06/02/2022
+ms.date: 06/14/2022
 ms.author: cshoe
 ---
 
-It's common for a front-end web app to call backend APIs. By default, Azure Static Web Apps provides built-in serverless API endpoints via [Azure Functions](../articles/static-web-apps/apis.md). If you'd rather expose existing Azure resources as API endpoints in your static web app, Azure Static Web Apps integrates with the following Azure services:
+API options for Static Web Apps include the following Azure services:
 
 * [Azure Functions](../articles/static-web-apps/apis.md)
 * [Azure API Management](../articles/static-web-apps/apis-api-management.md)
 * [Azure App Service](../articles/static-web-apps/apis-app-service.md)
 * [Azure Container Apps](../articles/static-web-apps/apis-container-apps.md)
-
-Key features of integrated APIs include:
-
-- **Integrated security** with direct access to user [authentication and role-based authorization](../articles/static-web-apps/user-information.md) data.
-- **Seamless routing** that makes the */api* route available to the front-end web app without requiring custom CORS rules.
-
-Each environment in a static web app can be configured with one type of backend API at a time. You can use the built-in, managed Azure Functions APIs, or you can integrate with one of the supported Azure services.
-
-> [!NOTE]
-> Backend APIs integration with other Azure services is only available in the Azure Static Web Apps Standard plan. Built-in, managed Azure Functions APIs are available in all Azure Static Web Apps plans.