Skip to content

Commit 58deec0

Browse files
laurabrenlaurabren
authored
Merge pull request #183204 from anthonychu/20211217-swa-backend-apis
Static Web Apps - Bring your own backend
2 parents 76e38dc + 9bf4245 commit 58deec0

17 files changed

+346
-32
lines changed

‎.openpublishing.publish.config.json

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -998,6 +998,7 @@
998998
"articles/spring-cloud/.openpublishing.redirection.spring-cloud.json",
999999
"articles/load-testing/.openpublishing.redirection.azure-load-testing.json",
10001000
"articles/azure-video-indexer/.openpublishing.redirection.azure-video-indexer.json",
1001-
"articles/machine-learning/.openpublishing.redirection.machine-learning.json"
1001+
"articles/machine-learning/.openpublishing.redirection.machine-learning.json",
1002+
"articles/static-web-apps/.openpublishing.redirection.static-web-apps.json"
10021003
]
10031004
}

‎articles/static-web-apps/.openpublishing.redirection.static-web-apps.json

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"redirections": [
3+
{
4+
"source_path_from_root": "/articles/static-web-apps/apis.md",
5+
"redirect_url": "/azure/static-web-apps/apis-functions",
6+
"redirect_document_id": false
7+
}
8+
]
9+
}

‎articles/static-web-apps/TOC.yml

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -23,12 +23,22 @@
2323
items:
2424
- name: APIs
2525
items:
26-
- name: API support with Azure Functions
27-
href: apis.md
28-
- name: Add an API
29-
href: add-api.md
30-
- name: Bring your own functions
31-
href: functions-bring-your-own.md
26+
- name: Overview
27+
href: apis-overview.md
28+
- name: Azure Functions
29+
items:
30+
- name: Integration options
31+
href: apis-functions.md
32+
- name: Add an API
33+
href: add-api.md
34+
- name: Bring your own functions
35+
href: functions-bring-your-own.md
36+
- name: Azure API Management
37+
href: apis-api-management.md
38+
- name: Azure App Service
39+
href: apis-app-service.md
40+
- name: Azure Container Apps
41+
href: apis-container-apps.md
3242
- name: Configuration
3343
items:
3444
- name: Configuration overview

‎articles/static-web-apps/add-api.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ ms.custom: devx-track-js
1515
You can add serverless APIs to Azure Static Web Apps that are powered by Azure Functions. This article demonstrates how to add and deploy an API to an Azure Static Web Apps site.
1616

1717
> [!NOTE]
18-
> The functions provided by default in Static Web Apps are pre-configured to provide secure API endpoints and only support HTTP-triggered functions. See [API support with Azure Functions](apis.md) for information on how they differ from standalone Azure Functions apps.
18+
> The functions provided by default in Static Web Apps are pre-configured to provide secure API endpoints and only support HTTP-triggered functions. See [API support with Azure Functions](apis-functions.md) for information on how they differ from standalone Azure Functions apps.
1919
2020
## Prerequisites
2121

‎articles/static-web-apps/apis-api-management.md

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
---
2+
title: API support in Azure Static Web Apps with Azure API Management
3+
description: Learn how to use Azure API Management with Azure Static Web Apps
4+
services: static-web-apps
5+
author: craigshoemaker
6+
ms.service: static-web-apps
7+
ms.topic: conceptual
8+
ms.date: 06/14/2022
9+
ms.author: cshoe
10+
---
11+
12+
# API support in Azure Static Web Apps with Azure API Management
13+
14+
[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.
15+
16+
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.
17+
18+
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.
19+
20+
All Azure API Management pricing tiers are available for use with Azure Static Web Apps.
21+
22+
[!INCLUDE [APIs overview](../../includes/static-web-apps-apis-overview.md)]
23+
24+
> [!NOTE]
25+
> The integration with Azure API Management is currently in preview and requires the Static Web Apps Standard plan.
26+
>
27+
> Currently, you cannot link an API Management service to a Static Web Apps [pull request environment](review-publish-pull-requests.md).
28+
29+
## Link an Azure API Management service
30+
31+
To link an Azure API Management service as the API backend for a static web app, follow these steps:
32+
33+
1. In the Azure portal, navigate to the static web app.
34+
35+
1. Select **APIs** from the navigation menu.
36+
37+
1. Locate the environment you want to link the API Management service to. Select **Link**.
38+
39+
1. In *Backend resource type*, select **API Management**.
40+
41+
1. In *Subscription*, select the subscription containing the Azure API Management service you want to link.
42+
43+
1. In *Resource name*, select the Azure API Management service.
44+
45+
1. Select **Link**.
46+
47+
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.
48+
49+
### Manage access to APIs
50+
51+
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)`.
52+
53+
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.
54+
55+
```json
56+
{
57+
"statusCode": 401,
58+
"message": "Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription."
59+
}
60+
```
61+
62+
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).
63+
64+
The linking process also automatically applies the following configuration to your API Management service:
65+
66+
* The product associated with the linked static web app is configured to require a subscription.
67+
* 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.
68+
* 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.
69+
* 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.
70+
71+
> [!IMPORTANT]
72+
> Changing the *validate-jwt* policy or regenerating the subscription's primary key will prevent your static web app from proxying requests to the API Management service. Do not modify or delete the subscription or product associated with your static web app while they are linked.
73+
74+
## Unlink an Azure API Management service
75+
76+
To unlink an Azure API Management service from a static web app, follow these steps:
77+
78+
1. In the Azure portal, navigate to the static web app.
79+
80+
1. Locate the environment that you want to unlink and select the API Management service name.
81+
82+
1. Select **Unlink**.
83+
84+
When the unlinking process is complete, requests to routes beginning with `/api/` are no longer proxied to your API Management service.
85+
86+
> [!NOTE]
87+
> The API Management product and subscription associated with the linked static web app are not automatically deleted. You can delete them from the API Management service.
88+
89+
## Next steps
90+
91+
> [!div class="nextstepaction"]
92+
> [API overview](apis-overview.md)

‎articles/static-web-apps/apis-app-service.md

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
title: API support in Azure Static Web Apps with Azure App Service
3+
description: Learn how to use Azure App Service with Azure Static Web Apps
4+
services: static-web-apps
5+
author: craigshoemaker
6+
ms.service: static-web-apps
7+
ms.topic: conceptual
8+
ms.date: 06/14/2022
9+
ms.author: cshoe
10+
---
11+
12+
# API support in Azure Static Web Apps with Azure App Service
13+
14+
[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.
15+
16+
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.
17+
18+
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.
19+
20+
All Azure App Service hosting plans are available for use with Azure Static Web Apps.
21+
22+
[!INCLUDE [APIs overview](../../includes/static-web-apps-apis-overview.md)]
23+
24+
> [!NOTE]
25+
> The integration with Azure API Management is currently in preview and requires the Static Web Apps Standard plan.
26+
>
27+
> You cannot link a web app to a Static Web Apps [pull request environment](review-publish-pull-requests.md).
28+
29+
## Link an Azure App Service Web App
30+
31+
To link a web app as the API backend for a static web app, follow these steps:
32+
33+
1. In the Azure portal, navigate to the static web app.
34+
35+
1. Select **APIs** from the navigation menu.
36+
37+
1. Locate the environment you want to link the API Management instance to. Select **Link**.
38+
39+
1. In *Backend resource type*, select **Web App**.
40+
41+
1. In *Subscription*, select the subscription containing the Azure App Service app you want to link.
42+
43+
1. In *Resource name*, select the Azure App Service app.
44+
45+
1. Select **Link**.
46+
47+
When the linking process is complete, requests to routes beginning with `/api` are proxied to the linked App Service app.
48+
49+
### Manage access to Azure App Service
50+
51+
Your App Service app is configured with an identity provider named `Azure Static Web Apps (Linked)` that permits only traffic that is proxied through the static web app. To make your App Service app accessible to other applications, update its authentication configuration to add another identity provider or change the security settings to allow unauthenticated access.
52+
53+
## Unlink an Azure App Service app
54+
55+
To unlink a web app from a static web app, follow these steps:
56+
57+
1. In the Azure portal, navigate to the static web app.
58+
59+
1. Select **APIs** from the navigation menu.
60+
61+
1. Locate the environment that you want to unlink and select the web app name.
62+
63+
1. Select **Unlink**.
64+
65+
When the unlinking process is complete, requests to routes beginning with `/api` are no longer proxied to your App Service app.
66+
67+
> [!NOTE]
68+
> 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.
69+
70+
## Next steps
71+
72+
> [!div class="nextstepaction"]
73+
> [API overview](apis-overview.md)

‎articles/static-web-apps/apis-container-apps.md

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
---
2+
title: API support in Azure Static Web Apps with Azure Container Apps
3+
description: Learn how to use Azure Container Apps with Azure Static Web Apps
4+
services: static-web-apps
5+
author: craigshoemaker
6+
ms.service: static-web-apps
7+
ms.topic: conceptual
8+
ms.date: 06/14/2022
9+
ms.author: cshoe
10+
---
11+
12+
# API support in Azure Static Web Apps with Azure Container Apps
13+
14+
[Azure Container Apps](../container-apps/overview.md) is a managed platform for hosting serverless containers and microservices.
15+
16+
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.
17+
18+
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.
19+
20+
[!INCLUDE [APIs overview](../../includes/static-web-apps-apis-overview.md)]
21+
22+
> [!NOTE]
23+
> The integration with Azure Container Apps is currently in preview and requires the Static Web Apps Standard plan.
24+
>
25+
> You cannot link a container app to a Static Web Apps [pull request environment](review-publish-pull-requests.md).
26+
27+
## Link a container app
28+
29+
To link a web app as the API backend for a static web app, follow these steps:
30+
31+
1. In the Azure portal, navigate to the static web app.
32+
33+
1. Select **APIs** from the navigation menu.
34+
35+
1. Locate the environment you want to link the API Management instance to. Select **Link**.
36+
37+
1. In *Backend resource type*, select **Container App**.
38+
39+
1. In *Subscription*, select the subscription containing the container app you want to link.
40+
41+
1. In *Resource name*, select the container app.
42+
43+
1. Select **Link**.
44+
45+
When the linking process is complete, requests to routes beginning with `/api` are proxied to the linked container app.
46+
47+
### Manage access to the container app
48+
49+
Your container app is configured with an identity provider named `Azure Static Web Apps (Linked)` that permits only traffic that is proxied through the static web app. To make your container app accessible to other applications, update its authentication configuration to add another identity provider or change the security settings to allow unauthenticated access.
50+
51+
## Unlink a container app
52+
53+
To unlink a container app from a static web app, follow these steps:
54+
55+
1. In the Azure portal, navigate to the static web app.
56+
57+
1. Select **APIs** from the navigation menu.
58+
59+
1. Locate the environment that you want to unlink and select the container app name.
60+
61+
1. Select **Unlink**.
62+
63+
When the unlinking process is complete, requests to routes beginning with `/api` are no longer proxied to your container app.
64+
65+
> [!NOTE]
66+
> 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.
67+
68+
## Next steps
69+
70+
> [!div class="nextstepaction"]
71+
> [API overview](apis-overview.md)

‎articles/static-web-apps/apis.md renamed to ‎articles/static-web-apps/apis-functions.md

Lines changed: 15 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,19 @@
11
---
22
title: API support in Azure Static Web Apps with Azure Functions
3-
description: Learn what API features Azure Static Web Apps supports
3+
description: Learn how to use Azure Functions with Azure Static Web Apps
44
services: static-web-apps
55
author: craigshoemaker
66
ms.service: static-web-apps
77
ms.topic: conceptual
8-
ms.date: 03/29/2022
8+
ms.date: 06/14/2022
99
ms.author: cshoe
1010
---
1111

1212
# API support in Azure Static Web Apps with Azure Functions
1313

14-
Azure Static Web Apps provides serverless API endpoints via [Azure Functions](../azure-functions/functions-overview.md). By using Azure Functions, APIs dynamically scale based on demand, and include the following features:
14+
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](apis-functions.md).
1515

16-
- **Integrated security** with direct access to user [authentication and role-based authorization](user-information.md) data.
17-
18-
- **Seamless routing** that makes the _api_ route available to the web app securely without requiring custom CORS rules.
19-
20-
Azure Static Web Apps APIs are supported by two possible configurations depending on the [hosting plan](plans.md#features):
16+
Azure Functions APIs in Static Web Apps are supported by two possible configurations depending on the [hosting plan](plans.md#features):
2117

2218
- **Managed functions**: By default, the API of a static web app is an Azure Functions application managed and deployed by Azure Static Web Apps associated with some restrictions.
2319

@@ -26,12 +22,12 @@ Azure Static Web Apps APIs are supported by two possible configurations dependin
2622
The following table contrasts the differences between using managed and existing functions.
2723

2824
| Feature | Managed Functions | Bring your own Functions |
29-
| --- | --- | --- |
30-
| Access to Azure Functions [triggers](../azure-functions/functions-triggers-bindings.md#supported-bindings) | Http only | All |
25+
|---|---|---|
26+
| Access to Azure Functions [triggers](../azure-functions/functions-triggers-bindings.md#supported-bindings) | HTTP only | All |
3127
| 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 |
3228
| Supported Azure Functions [hosting plans](../azure-functions/functions-scale.md) | Consumption | Consumption<br>Premium<br>Dedicated |
3329
| [Integrated security](user-information.md) with direct access to user authentication and role-based authorization data | ✔ | ✔ |
34-
| [Routing integration](./configuration.md?#routes) that makes the _api_ route available to the web app securely without requiring custom CORS rules. | ✔ | ✔ |
30+
| [Routing integration](./configuration.md?#routes) that makes the `/api` route available to the web app securely without requiring custom CORS rules. | ✔ | ✔ |
3531
| [Durable Functions](../azure-functions/durable/durable-functions-overview.md) programming model | ✕ | ✔ |
3632
| [Managed identity](../app-service/overview-managed-identity.md) | ✕ | ✔ |
3733
| [Azure App Service Authentication and Authorization](../app-service/configure-authentication-provider-aad.md) token management | ✕ | ✔ |
@@ -40,29 +36,31 @@ The following table contrasts the differences between using managed and existing
4036

4137
<sup>1</sup> To specify the runtime version in managed functions, add a configuration file to your frontend app and set the [`apiRuntime` property](configuration.md#platform). Support is subject to the [Azure Functions language runtime support policy](../azure-functions/language-support-policy.md).
4238

39+
[!INCLUDE [APIs overview](../../includes/static-web-apps-apis-overview.md)]
40+
4341
## Configuration
4442

45-
API endpoints are available to the web app through the _api_ route.
43+
API endpoints are available to the web app through the `api` route.
4644

4745
| Managed functions | Bring your own functions |
48-
| --- | --- |
49-
| 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. |
46+
|---|---|
47+
| 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. |
5048

5149
## Troubleshooting and logs
5250

5351
Logs are only available if you add [Application Insights](monitor.md).
5452

5553
| Managed functions | Bring your own functions |
56-
| --- | --- |
54+
|---|---|
5755
| Turn on logging by enabling Application Insights on your static web app. | Turn on logging by enabling Application Insights on your Azure Functions app. |
5856

5957
## Constraints
6058

61-
- The API route prefix must be _api_.
59+
- The API route prefix must be `/api`.
6260
- Route rules for API functions only support [redirects](configuration.md#defining-routes) and [securing routes with roles](configuration.md#securing-routes-with-roles).
6361

6462
| Managed functions | Bring your own functions |
65-
| --- | --- |
63+
|---|---|
6664
| <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> |
6765

6866
## Next steps

0 commit comments

Comments
 (0)