You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
title: Customize an HTTP endpoint in Azure Functions
3
-
description: Learn how to customize an HTTP trigger endpoint in Azure Functions
3
+
description: Learn how to customize an HTTP trigger endpoint in Azure Functions.
4
4
author: mattchenderson
5
-
ms.topic: conceptual
6
-
ms.date: 04/27/2020
7
5
ms.author: mahender
6
+
ms.service: azure-functions
7
+
ms.topic: how-to
8
+
ms.date: 06/27/2024
8
9
ms.custom: mvc
10
+
11
+
#Customer intent: As a developer, I want to customize HTTP trigger endpoints in Azure Functions so that I can build a highly scalable API.
9
12
---
10
13
11
14
# Customize an HTTP endpoint in Azure Functions
12
15
13
-
In this article, you learn how Azure Functions allows you to build highly scalable APIs. Azure Functions comes with a collection of built-in HTTP triggers and bindings, which make it easy to author an endpoint in various languages, including Node.js, C#, and more. In this article, you'll customize an HTTP trigger to handle specific actions in your API design. You'll also prepare for growing your API by integrating it with Azure Functions Proxies and setting up mock APIs. These tasks are accomplished on top of the Functions serverless compute environment, so you don't have to worry about scaling resources - you can just focus on your API logic.
16
+
In this article, you learn how to build highly scalable APIs with Azure Functions by customizing an HTTP trigger to handle specific actions in your API design. Azure Functions includes a collection of built-in HTTP triggers and bindings, which make it easy to author an endpoint in various languages, including Node.js, C#, and more. You also prepare to grow your API by integrating it with Azure Functions proxies and setting up mock APIs. Because these tasks are accomplished on top of the Functions serverless compute environment, you don't need to be concerned about scaling resources. Instead, you can just focus on your API logic.
The resulting function will be used for the rest of this article.
24
+
After you create this function app, you can follow the procedures in this article.
22
25
23
26
## Sign in to Azure
24
27
25
28
Sign in to the [Azure portal](https://portal.azure.com) with your Azure account.
26
29
27
30
## Customize your HTTP function
28
31
29
-
By default, your HTTP trigger function is configured to accept any HTTP method. You can also use the default URL, `https://<yourapp>.azurewebsites.net/api/<funcname>?code=<functionkey>`. In this section, you modify the function to respond only to GET requests with `/api/hello`.
32
+
By default, you configure your HTTP trigger function to accept any HTTP method. In this section, you modify the function to respond only to GET requests with `/api/hello`. You can use the default URL, `https://<yourapp>.azurewebsites.net/api/<funcname>?code=<functionkey>`:
30
33
31
34
1. Navigate to your function in the Azure portal. Select **Integration** in the left menu, and then select **HTTP (req)** under **Trigger**.
32
35
33
-
:::image type="content" source="./media/functions-create-serverless-api/customizing-http.png" alt-text="Customizing an HTTP function":::
36
+
:::image type="content" source="./media/functions-create-serverless-api/customizing-http.png" alt-text="Screenshot that shows how to edit the HTTP trigger settings of a function." lightbox="./media/functions-create-serverless-api/customizing-http.png":::
34
37
35
38
1. Use the HTTP trigger settings as specified in the following table.
36
39
@@ -40,162 +43,160 @@ By default, your HTTP trigger function is configured to accept any HTTP method.
40
43
| Authorization level | Anonymous | Optional: Makes your function accessible without an API key |
41
44
| Selected HTTP methods | GET | Allows only selected HTTP methods to be used to invoke this function |
42
45
43
-
You didn't include the `/api` base path prefix in the route template, because it's handled by a global setting.
46
+
Because a global setting handles the `/api` base path prefix in the route template, you don't need to set it here.
44
47
45
48
1. Select **Save**.
46
49
47
-
For more information about customizing HTTP functions, see [Azure Functions HTTP bindings](./functions-bindings-http-webhook.md).
50
+
For more information about customizing HTTP functions, see [Azure Functions HTTP triggers and bindings overview](./functions-bindings-http-webhook.md).
48
51
49
52
### Test your API
50
53
51
54
Next, test your function to see how it works with the new API surface:
52
-
1. On the function page, select **Code + Test** from the left menu.
53
55
54
-
1. Select **Get function URL** from the top menu and copy the URL. Confirm that it now uses the `/api/hello` path.
55
-
56
-
1. Copy the URL into a new browser tab or your preferred REST client.
56
+
1. On the **Function** page, select **Code + Test** from the left menu.
57
+
58
+
1. Select **Get function URL** from the top menu and copy the URL. Confirm that your function now uses the `/api/hello` path.
59
+
60
+
1. Copy the URL to a new browser tab or your preferred REST client. Browsers use GET by default.
57
61
58
-
Browsers use GET by default.
59
-
60
-
1. Add parameters to the query string in your URL.
62
+
1. Add parameters to the query string in your URL. For example, `/api/hello/?name=John`.
61
63
62
-
For example, `/api/hello/?name=John`.
63
-
64
-
1. Press Enter to confirm that it's working. You should see the response, "*Hello John*."
64
+
1. Press Enter to confirm that your function is working. You should see the response, "*Hello John*."
65
65
66
-
1. You can also try calling the endpoint with another HTTP method to confirm that the function isn't executed. To do so, use a REST client, such as cURL, Postman, or Fiddler.
66
+
1. You can also call the endpoint with another HTTP method to confirm that the function isn't executed. To do so, use a REST client, such as cURL, Postman, or Fiddler.
67
67
68
68
## Proxies overview
69
69
70
-
In the next section, you'll surface your API through a proxy. Azure Functions Proxies allows you to forward requests to other resources. You define an HTTP endpoint just like with HTTP trigger. However, instead of writing code to execute when that endpoint is called, you provide a URL to a remote implementation. Doing so allows you to compose multiple API sources into a single API surface, which is easy for clients to consume, which is useful if you wish to build your API as microservices.
70
+
In the next section, you surface your API through a proxy. Azure Functions proxies allow you to forward requests to other resources. You define an HTTP endpoint as you would with an HTTP trigger. However, instead of writing code to execute when that endpoint is called, you provide a URL to a remote implementation. Doing so allows you to compose multiple API sources into a single API surface, which is easier for clients to consume, and is useful if you wish to build your API as microservices.
71
71
72
72
A proxy can point to any HTTP resource, such as:
73
-
- Azure Functions
73
+
74
+
- Azure Functions
74
75
- API apps in [Azure App Service](../app-service/overview.md)
75
76
- Docker containers in [App Service on Linux](../app-service/overview.md#app-service-on-linux)
76
77
- Any other hosted API
77
78
78
-
To learn more about proxies, see [Working with Azure Functions Proxies].
79
+
To learn more about Azure Functions proxies, see [Work with legacy proxies].
79
80
80
81
> [!NOTE]
81
-
> Proxies is available in Azure Functions versions 1.x to 3.x.
82
+
> Azure Functions proxies is available in Azure Functions versions 1.x to 3.x.
82
83
83
84
## Create your first proxy
84
85
85
-
In this section, you create a new proxy, which serves as a frontend to your overall API.
86
+
In this section, you create a new proxy, which serves as a frontend to your overall API.
86
87
87
-
### Setting up the frontend environment
88
+
### Set up the frontend environment
88
89
89
-
Repeat the steps to[Create a function app](./functions-get-started.md) to create a new function app in which you'll create your proxy. This new app's URL serves as the frontend for our API, and the function app you were previously editing serves as a backend.
90
+
Repeat the steps in[Create a function app](./functions-create-function-app-portal.md#create-a-function-app) to create a new function app in which you create your proxy. This new app's URL serves as the frontend for our API, and the function app you previously edited serves as a backend:
90
91
91
92
1. Navigate to your new frontend function app in the portal.
92
-
1. Select **Configuration** and choose **Application Settings**.
93
-
1. Scroll down to **Application settings**, where key/value pairs are stored, and create a new setting with the key `HELLO_HOST`. Set its value to the host of your backend function app, such as `<YourBackendApp>.azurewebsites.net`. This value is part of the URL that you copied earlier when testing your HTTP function. You'll reference this setting in the configuration later.
93
+
1. Expand **Settings**, and then select **Environment variables**.
94
+
1. Select the **App settings** tab, where key/value pairs are stored.
95
+
1. Select **+ Add** to create a new setting. Enter **HELLO_HOST** for its **Name** and set its **Value** to the host of your backend function app, such as `<YourBackendApp>.azurewebsites.net`.
94
96
95
-
> [!NOTE]
96
-
> App settings are recommended for the host configuration to prevent a hard-coded environment dependency for the proxy. Using app settings means that you can move the proxy configuration between environments, and the environment-specific app settings will be applied.
97
+
This value is part of the URL that you copied earlier when you tested your HTTP function. You later reference this setting in the configuration.
97
98
98
-
1. Select **Save**.
99
+
> [!NOTE]
100
+
> It's recommended that you use app settings for the host configuration to prevent a hard-coded environment dependency for the proxy. Using app settings means that you can move the proxy configuration between environments, and the environment-specific app settings will be applied.
101
+
102
+
1. Select **Apply** to save the new setting. On the **App settings** tab, select **Apply**, and then select **Confirm** to restart the function app.
99
103
100
-
### Creating a proxy on the frontend
104
+
### Create a proxy on the frontend
101
105
102
106
1. Navigate back to your front-end function app in the portal.
103
107
104
-
1. In the left-hand menu, select **Proxies**, and then select **Add**.
108
+
1. In the left-hand menu, expand **Functions**, select **Proxies**, and then select **Add**.
105
109
106
-
1. On the **New Proxy** page, use the settings in the following table, and then select **Create**.
110
+
1. On the **New proxy** page, use the settings in the following table, and then select **Create**.
107
111
108
112
| Field | Sample value | Description |
109
113
|---|---|---|
110
114
| Name | HelloProxy | A friendly name used only for management |
111
115
| Route template | /api/remotehello | Determines what route is used to invoke this proxy |
112
116
| Backend URL | https://%HELLO_HOST%/api/hello | Specifies the endpoint to which the request should be proxied |
113
117
114
-
115
-
:::image type="content" source="./media/functions-create-serverless-api/creating-proxy.png" alt-text="Creating a proxy":::
118
+
:::image type="content" source="./media/functions-create-serverless-api/creating-proxy.png" alt-text="Screenshot that shows the settings in the New proxy page." lightbox="./media/functions-create-serverless-api/creating-proxy.png":::
116
119
117
-
Azure Functions Proxies doesn't provide the `/api` base path prefix, which must be included in the route template. The `%HELLO_HOST%` syntax references the app setting you created earlier. The resolved URL will point to your original function.
120
+
Because Azure Functions proxies don't provide the `/api` base path prefix, you must include it in the route template. The `%HELLO_HOST%` syntax references the app setting you created earlier. The resolved URL points to your original function.
118
121
119
122
1. Try out your new proxy by copying the proxy URL and testing it in the browser or with your favorite HTTP client:
Next, you'll use a proxy to create a mock API for your solution. This proxy allows client development to progress, without needing the backend fully implemented. Later in development, you can create a new function app, which supports this logic and redirect your proxy to it.
128
-
129
-
To create this mock API, we'll create a new proxy, this time using the [App Service Editor](https://github.com/projectkudu/kudu/wiki/App-Service-Editor). To get started, navigate to your function app in the portal. Select **Platform features**, and under **Development Tools** find **App Service Editor**. The App Service Editor opens in a new tab.
130
-
131
-
Select `proxies.json` in the left navigation. This file stores the configuration for all of your proxies. If you use one of the [Functions deployment methods](./functions-continuous-deployment.md), you maintain this file in source control. To learn more about this file, see [Proxies advanced configuration](./legacy-proxies.md#advanced-configuration).
132
-
133
-
If you've followed along so far, your proxies.json should look like as follows:
134
-
135
-
```json
136
-
{
137
-
"$schema": "http://json.schemastore.org/proxies",
138
-
"proxies": {
139
-
"HelloProxy": {
140
-
"matchCondition": {
141
-
"route": "/api/remotehello"
142
-
},
143
-
"backendUri": "https://%HELLO_HOST%/api/hello"
144
-
}
145
-
}
146
-
}
147
-
```
148
-
149
-
Next, you'll add your mock API. Replace your proxies.json file with the following code:
"description": "Awesome developer and master of serverless APIs",
172
-
"skills": [
173
-
"Serverless",
174
-
"APIs",
175
-
"Azure",
176
-
"Cloud"
177
-
]
178
-
}
179
-
}
180
-
}
181
-
}
182
-
}
183
-
```
184
-
185
-
This code adds a new proxy, `GetUserByName`, without the `backendUri` property. Instead of calling another resource, it modifies the default response from Proxies using a response override. Request and response overrides can also be used with a backend URL. This technique is useful when proxying to a legacy system, where you might need to modify headers, query parameters, and so on. To learn more about request and response overrides, see [Modifying requests and responses in Proxies](./legacy-proxies.md).
186
-
187
-
Test your mock API by calling the `<YourProxyApp>.azurewebsites.net/api/users/{username}` endpoint using a browser or your favorite REST client. Be sure to replace _{username}_ with a string value representing a username.
188
-
189
-
## Next steps
190
-
191
-
In this article, you learned how to build and customize an API on Azure Functions. You also learned how to bring multiple APIs, including mocks, together as a unified API surface. You can use these techniques to build out APIs of any complexity, all while running on the serverless compute model provided by Azure Functions.
192
-
193
-
The following references may be helpful as you develop your API further:
-[Documenting an Azure Functions API (preview)](./functions-openapi-definition.md)
198
-
199
-
200
-
[Create your first function]: ./functions-get-started.md
201
-
[Working with Azure Functions Proxies]: ./legacy-proxies.md
130
+
Next, you use a proxy to create a mock API for your solution. This proxy allows client development to progress, without needing to fully implement the backend. Later in development, you can create a new function app that supports this logic, and redirect your proxy to it:
131
+
132
+
1. To create this mock API, create a new proxy, this time using [App Service Editor](https://github.com/projectkudu/kudu/wiki/App-Service-Editor). To get started, navigate to your function app in the Azure portal. Select **Platform features**, and then select **App Service Editor** under **Development Tools**.
133
+
134
+
The App Service Editor opens in a new tab.
135
+
136
+
1. Select `proxies.json` in the left pane. This file stores the configuration for all of your proxies. If you use one of the [Functions deployment methods](./functions-continuous-deployment.md), you maintain this file in source control. For more information about this file, see [Proxies advanced configuration](./legacy-proxies.md#advanced-configuration).
137
+
138
+
Your *proxies.json* file should appear as follows:
139
+
140
+
```json
141
+
{
142
+
"$schema": "http://json.schemastore.org/proxies",
143
+
"proxies": {
144
+
"HelloProxy": {
145
+
"matchCondition": {
146
+
"route": "/api/remotehello"
147
+
},
148
+
"backendUri": "https://%HELLO_HOST%/api/hello"
149
+
}
150
+
}
151
+
}
152
+
```
153
+
154
+
1. Add your mock API. Replace your *proxies.json* file with the following code:
"description": "Awesome developer and master of serverless APIs",
177
+
"skills": [
178
+
"Serverless",
179
+
"APIs",
180
+
"Azure",
181
+
"Cloud"
182
+
]
183
+
}
184
+
}
185
+
}
186
+
}
187
+
}
188
+
```
189
+
190
+
This code adds a new proxy, `GetUserByName`, which omits the `backendUri` property. Instead of calling another resource, it modifies the default response from Azure Functions proxies by using a response override. You can also use request and response overrides with a backend URL. This technique is useful when you proxy to a legacy system, where you might need to modify headers, query parameters, and so on. For more information about request and response overrides, see [Modify requests and responses](./legacy-proxies.md#modify-requests-responses).
191
+
192
+
1. Test your mock API by calling the `<YourProxyApp>.azurewebsites.net/api/users/{username}` endpoint with a browser or your favorite REST client. Replace *{username}* with a string value that represents a username.
193
+
194
+
## Related content
195
+
196
+
In this article, you learned how to build and customize an API with Azure Functions. You also learned how to bring multiple APIs, including mock APIS, together as a unified API surface. You can use these techniques to build out APIs of any complexity, all while running on the serverless compute model provided by Azure Functions.
197
+
198
+
For more information about developing your API:
199
+
200
+
-[Azure Functions HTTP triggers and bindings overview](./functions-bindings-http-webhook.md)
201
+
-[Work with legacy proxies](./legacy-proxies.md)
202
+
-[Expose serverless APIs from HTTP endpoints using Azure API Management](./functions-openapi-definition.md)
0 commit comments