Draft of APIM forward serverless API docs

Author: ggailey777

articles/azure-functions/functions-proxies.md

@@ -7,29 +7,43 @@ ms.date: 09/07/2022
 ---
 # Serverless REST APIs using Azure Functions
 
-Azure Functions is an essential compute service that you use to build serverless REST-based APIs. HTTP triggers expose REST endpoints that can be called by your clients, like browsers, mobile apps, and other backend services. With [native support for routes](functions-bindings-http-webhook-trigger.md#customize-the-http-endpoint), a single HTTP triggered function can expose a highly functional REST API. Functions even natively provides a basic key-based authorization scheme to help limit access only to specific clients. For more information, see [Azure Functions HTTP trigger](functions-bindings-http-webhook-trigger.md)
+Azure Functions is an essential compute service that you use to build serverless REST-based APIs. HTTP triggers expose REST endpoints that can be called by your clients, like browsers, mobile apps, and other backend services. With [native support for routes](functions-bindings-http-webhook-trigger.md#customize-the-http-endpoint), a single HTTP triggered function can expose a highly-functional REST API. Functions also provides its own basic key-based authorization scheme to help limit access only to specific clients. For more information, see [Azure Functions HTTP trigger](functions-bindings-http-webhook-trigger.md)
 
-In some scenarios, you may need your API to support a more complex set of REST behaviors. For example, you may need to combine more multiple HTTP triggered functions into a single API. You might also want to pass requests through to one or more backend REST-based services. Finally, you might want to implement a higher-degree of security for your API and potentially monetize its use.
+In some scenarios, you may need your API to support a more complex set of REST behaviors. For example, you may need to combine multiple HTTP function endpoints into a single API. You might also want to pass requests through to one or more backend REST-based services. Finally, your APIs might require a higher-degree of security that let you monetize its use.
 
-The recommend approach to build more complex and robust APIs based on your functions is to leverage the comprehensive API services provided by [Azure API Management](../api-management/api-management-key-concepts.md). The legacy [Functions Proxies feature](legacy-proxies.md) also provided a subset of these features for version 3.x and older version of the Functions runtime. The following table compares API Management with the legacy Proxies feature:
+## API Management
 
-| | API Management | Functions proxies |
-| --- | --- | --- |
-| Runtime versions | All | v1.x-v3.x<br/>v4.x (legacy-only)  |  
-| Hosting | API Management  | Functions| 
+Today, the recommended approach to build more complex and robust APIs based on your functions is to leverage the comprehensive API services provided by [Azure API Management](../api-management/api-management-key-concepts.md). 
+API Management uses a policy-based model to let you control routing, security, and OpenAPI integration. It also supports advanced policies like rate limiting monetization. 
 
-Azure Functions proxies 
+API Management lets you import an existing function app. After import, each HTTP triggered function endpoint becomes an API that you can modify and manage. After import, you can also use API Management to generated an OpenAPI definition file for your APIs. During import, any endpoints with an `admin` [authorization level](functions-bindings-http-webhook-trigger.md#http-auth) are ignored. For more information about using API Management with Functions, see the following articles:
 
-We are no longer investing in Azure Functions proxy support and strongly recommend customers to Azure API Management (in premium or consumption tier) when building API's with Azure Functions. It provides the same capabilities as Functions Proxies as well as other tools for defining, securing, and maintaining APIs, such as OpenAPI integration, rate limiting, and advanced policies. The key reason for this decision is to avoid duplication of functionality and provide a richer set of capabilities as detailed in [Azure APIM](https://docs.microsoft.com/en-us/azure/api-management/). 
+| Article | Description |
+| --- | --- |
+| [Expose serverless APIs from HTTP endpoints using Azure API Management](functions-openapi-definition.md) | Shows how to create a new API Management instance from an exsiting function app in the Azure portal. Supports all languages. |
+| [Create serverless APIs in Visual Studio using Azure Functions and API Management integration](openapi-apim-integrate-visual-studio.md) | Shows how to use Visual Studio to create a C# project that leverages the [OpenAPI extension](https://github.com/Azure/azure-functions-openapi-extension). The OpenAPI extension lets you define your .NET APIs by applying attributes directly to your C# code. |
+| [Quickstart: Create a new Azure API Management service instance by using the Azure portal](../api-management/get-started-create-service-instance.md) | Create a new API Management instance in the portal. After you create an API Management instance, you can connect it to your function app. Other non-portal creatation methods are supported. |
+| [Import an Azure function app as an API in Azure API Management](../api-management/import-function-app-as-api.md) | Shows how to import an existing function app to expose existsing HTTP trigger endpoints as a managed API. This article supports both creating a new API and adding the endpoints to an existing managed API. |
 
-This article has basic pointers on migrating to APIM, however we are fully aware that it is not exhaustive and would be interested to learn more if Azure API Management does not fit your scenarios or if you have challenges. Please fill out this survey OR create issues on <github repo> so we can build seamless integration experiences.
+After you have your function app endpoints exposed by using API Management, the following articles provide general information about how to manage your Functions-based APIs in the API Management instance.
 
-This article explains how to configure and work with Azure Functions Proxies. With this feature, you can specify endpoints on your function app that are implemented by another resource. You can use these proxies to break a large API into multiple function apps (as in a microservice architecture), while still presenting a single API surface for clients.
+| Article | Description |
+| --- | --- |
+| [Edit an API](../api-management/edit-api.md) | Shows you how to work with an existing API hosted in API Management. | 
+| [Policies in Azure API Management](../api-management/api-management-howto-policies.md) | In API Management, publishers can change API behavior through configuration using policies. Policies are a collection of statements that are run sequentially on the request or response of an API. |
+| [API Management policy reference](../api-management/api-management-policies.md) | Reference that details all supported API Management policies. |
+| [API Management policy samples](/azure/api-management/policies/) | Helpful collection of samples using API Management policies in key scenarios. |
 
-Standard Functions billing applies to proxy executions. For more information, see [Azure Functions pricing](https://azure.microsoft.com/pricing/details/functions/).
+## Functions Proxies
 
-> [!NOTE] 
-> Proxies is available in Azure Functions [versions](./functions-versions.md) 1.x to 3.x. In general, you will need to upgrade your Function applications to the 4.x host runtime by December 13th, 2022 due to EOL support. See more [here], so migrating to using API Management will ensure your applications are continued to be supported. Only for cases where migration is absolutely not possible, we are adding proxy support back in Functions 4.x, so your applications can keep running without disruption.
+The legacy [Functions Proxies feature](legacy-proxies.md) also provides a set of basic API functionality for version 3.x and older version of the Functions runtime. 
 
+> [!IMPORTANT] 
+> Azure Functions proxies is a legacy feature of Azure Functions [runtime versions](./functions-versions.md) 1.x to 3.x. Proxies are only supported in version 4.x to allow you to successfully upgrade your function apps to the latest runtime version. To take advantage of a more complete set of API behaviors, you should switch to using [Azure API Management](../api-management/api-management-key-concepts.md) for exposing and managing your APIs at the earliest possible convenience.
+
+Some basic hints for how to perform equivalent tasks using API Management have been added to the [Functions Proxies article](legacy-proxies.md). We don't currently have documentation or tools to help you migrate an existing Functions Proxies implementation to API Management.
 
 ## Next steps
+
+> [!div class="nextstepaction"]
+> [Expose serverless APIs from HTTP endpoints using Azure API Management](functions-openapi-definition.md)

articles/azure-functions/legacy-proxies.md

@@ -5,56 +5,39 @@ ms.topic: conceptual
 ms.date: 09/08/2022
 
 ---
-# Azure Functions Proxies (To be Deprecated - Sep 2025)
+# Work with legacy Proxies Azure Functions
 
-Azure Functions proxies 
-
-We are no longer investing in Azure Functions proxy support and strongly recommend customers to Azure API Management (in premium or consumption tier) when building API's with Azure Functions. It provides the same capabilities as Functions Proxies as well as other tools for building and maintaining APIs, such as OpenAPI integration, rate limiting, and advanced policies. The key reason for this decision is to avoid duplication of functionality and provide a richer set of capabilities as detailed in [Azure APIM](https://docs.microsoft.com/en-us/azure/api-management/). 
-
-This article has basic pointers on migrating to APIM, however we are fully aware that it is not exhaustive and would be interested to learn more if Azure API Management does not fit your scenarios or if you have challenges. Please fill out this survey OR create issues on <github repo> so we can build seamless integration experiences.
+> [!IMPORTANT] 
+> Azure Functions proxies is a legacy feature of Azure Functions [runtime versions](./functions-versions.md) 1.x to 3.x. Proxies are only supported in version 4.x to allow you to successfully upgrade your function apps to the latest runtime version. To take advantage of a more complete set of API behaviors, you should switch to using [Azure API Management](../api-management/api-management-key-concepts.md) for exposing and managing your APIs at the earliest possible convenience.
+> 
+> To help make it easier to migrate from existing proxy implemetations, this article links to equivalent API Management content, when available.
 
 This article explains how to configure and work with Azure Functions Proxies. With this feature, you can specify endpoints on your function app that are implemented by another resource. You can use these proxies to break a large API into multiple function apps (as in a microservice architecture), while still presenting a single API surface for clients.
 
 Standard Functions billing applies to proxy executions. For more information, see [Azure Functions pricing](https://azure.microsoft.com/pricing/details/functions/).
 
-> [!NOTE] 
-> Proxies is available in Azure Functions [versions](./functions-versions.md) 1.x to 3.x. In general, you will need to upgrade your Function applications to the 4.x host runtime by December 13th, 2022 due to EOL support. See more [here], so migrating to using API Management will ensure your applications are continued to be supported. Only for cases where migration is absolutely not possible, we are adding proxy support back in Functions 4.x, so your applications can keep running without disruption.
-
-## <a name="create"></a>Create a proxy or an APIM instance
+## <a name="create"></a>Create a proxy
 
-# [Proxy](#tab/Proxy)
-This section shows you how to create a proxy in the Functions portal. 
+> [!IMPORTANT] 
+> For equivalent content using API Management, see [Expose serverless APIs from HTTP endpoints using Azure API Management](functions-openapi-definition.md). 
 
-> [!NOTE]  
-> Not all languages and operating system combinations support in-portal editing. If you're unable to create a proxy in the portal, you can instead manually create a _proxies.json_ file in the root of your function app project folder. To learn more about portal editing support, see [Language support details](functions-create-function-app-portal.md#language-support-details). 
+Proxies are defined in the _proxies.json_ file in the root of your function app. The steps in this section shows you how to use the Azure portal to create this file in your function app. Not all languages and operating system combinations support in-portal editing. If can't modify your function app files in the portal, instead create and deploy the equivalent `proxies.json` file from the root of your local project folder. To learn more about portal editing support, see [Language support details](functions-create-function-app-portal.md#language-support-details). 
 
 1. Open the [Azure portal], and then go to your function app.
-2. In the left pane, select **Proxies** and then select **+Add**.
-3. Provide a name for your proxy.
-4. Configure the endpoint that's exposed on this function app by specifying the **route template** and **HTTP methods**. These parameters behave according to the rules for [HTTP triggers].
-5. Set the **backend URL** to another endpoint. This endpoint could be a function in another function app, or it could be any other API. The value does not need to be static, and it can reference [application settings] and [parameters from the original client request].
-6. Click **Create**.
-
-Your proxy now exists as a new endpoint on your function app. From a client perspective, it is equivalent to an HttpTrigger in Azure Functions. You can try out your new proxy by copying the Proxy URL and testing it with your favorite HTTP client.
-
-# [APIM](#tab/APIM)
-This section shows you how to create an APIM instance with APIs imported/published from your Http triggered function applications.
-
-Create a new Azure API Management service instance [Quickstart] (https://docs.microsoft.com/en-us/azure/api-management/get-started-create-service-instance). You may also use Azure CLI, Powershell, Visual Studio Code, Bicep or ARM Template to create an APIM instance.
-
-Once the instance is created, you can:
-1. [Import an Azure Function App as a new API] (https://docs.microsoft.com/en-us/azure/api-management/import-function-app-as-api#add-new-api-from-azure-function-app)
-2. [Append Azure Function App to an existing API] (https://docs.microsoft.com/en-us/azure/api-management/import-function-app-as-api#append-azure-function-app-to-api)
+1. In the left pane, select **Proxies** and then select **+Add**.
+1. Provide a name for your proxy.
+1. Configure the endpoint that's exposed on this function app by specifying the **route template** and **HTTP methods**. These parameters behave according to the rules for [HTTP triggers].
+1. Set the **backend URL** to another endpoint. This endpoint could be a function in another function app, or it could be any other API. The value does not need to be static, and it can reference [application settings] and [parameters from the original client request].
+1. Select **Create**.
 
-Alternatively, if you are using Visual Studio for your Functions project, you can publish it to a Function App in Azure with API Management integration as detailed [here] (https://docs.microsoft.com/en-us/azure/azure-functions/openapi-apim-integrate-visual-studio).
-
-You can now refine your APIs in API Management in the portal by [editing your OpenAPI definition] (https://docs.microsoft.com/en-us/azure/api-management/edit-api)
+Your proxy now exists as a new endpoint on your function app. From a client perspective, it's the same as an HttpTrigger in Functions. You can try out your new proxy by copying the **Proxy URL** and testing it with your favorite HTTP client.
 
 ## <a name="modify-requests-responses"></a>Modify requests and responses
 
-# [Proxy](#tab/Proxy)
+> [!IMPORTANT] 
+> API Management lets you can change API behavior through configuration using policies. Policies are a collection of statements that are run sequentially on the request or response of an API. For more information about API Management policies, see [Policies in Azure API Management](../api-management/api-management-howto-policies.md). 
 
-With Azure Functions Proxies, you can modify requests to and responses from the back-end. These transformations can use variables as defined in [Use variables].
+With proxies, you can modify requests to and responses from the back-end. These transformations can use variables as defined in [Use variables].
 
 ### <a name="modify-backend-request"></a>Modify the back-end request
 
@@ -77,7 +60,6 @@ You can use `localhost` to reference a function inside the same function app dir
 
 `"backendUri": "https://localhost/api/httptriggerC#1"` will reference a local HTTP triggered function at the route `/api/httptriggerC#1`
 
- 
 >[!Note]  
 >If your function uses *function, admin or sys* authorization levels, you will need to provide the code and clientId, as per the original function URL. In this case the reference would look like: `"backendUri": "https://localhost/api/httptriggerC#1?code=<keyvalue>&clientId=<keyname>"` We recommend storing these keys in [application settings] and referencing those in your proxies. This avoids storing secrets in your source code. 
 
@@ -114,20 +96,6 @@ For example, a back-end URL of *https://%ORDER_PROCESSING_HOST%/api/orders* woul
 > [!TIP] 
 > Use application settings for back-end hosts when you have multiple deployments or test environments. That way, you can make sure that you are always talking to the right back-end for that environment.
 
-# [APIM](#tab/APIM)
-
-In Azure API Management, API publishers can change API behavior through configuration using policies. Policies are a collection of statements that are run sequentially on the request or response of an API.
-
-Policies are applied inside the gateway between the API consumer and the managed API. While the gateway receives requests and forwards them, unaltered, to the underlying API, a policy can apply changes to both the inbound request and outbound response.
-
-You can configure Azure API Management policies at different scopes namely Global, Product, API or Operation.
-
-Learn more about [APIM Policies](https://docs.microsoft.com/en-us/azure/api-management/api-management-howto-policies#-understanding-policy-configuration).
-
-To get started with inbound, outbound and on-error policies, check out the [samples](https://docs.microsoft.com/en-us/azure/api-management/policies/). 
-
-Refer an exhaustive list of [all API Management policies](https://docs.microsoft.com/en-us/azure/api-management/api-management-policies).
-
 ## <a name="debugProxies"></a>Troubleshoot Proxies
 
 By adding the flag `"debug":true` to any proxy in your `proxies.json` you will enable debug logging. Logs are stored in `D:\home\LogFiles\Application\Proxies\DetailedTrace` and accessible through the advanced tools (kudu). Any HTTP responses will also contain a `Proxy-Trace-Location` header with a URL to access the log file.