Azure Functions Proxies

Azure Functions Proxies provide a way to create a single HTTP endpoint that aggregates multiple backend HTTP APIs or other Azure Functions. This is useful for scenarios where you want to expose a unified API surface, abstract underlying implementation details, or combine responses from different services.

What are Function Proxies?

A proxy is a configuration in your Azure Functions app that defines an incoming HTTP request route and maps it to one or more actions. These actions can include:

• Forwarding the request to a specific backend URL (another Azure Function, a web API, etc.).
• Modifying the request before it's sent.
• Modifying the response before it's returned to the client.
• Returning a static response.

Key Concepts

• Route: The URL path that clients will call to invoke the proxy.
• Backend URL: The URL of the actual resource or API the proxy will forward the request to.
• Request Overrides: Allow you to change headers, query parameters, or the HTTP method of the incoming request.
• Response Overrides: Allow you to change headers, status codes, or the response body before it's sent back to the client.
• Conditions: Define criteria (e.g., request method, headers) that must be met for the proxy to execute.

Defining Proxies

Proxies are defined in a file named proxies.json in the root of your Azure Functions project.

Example proxies.json

{
    "$schema": "http://json.schemastore.org/proxies",
    "proxies": {
        "myApiProxy": {
            "matchCondition": {
                "methods": [ "GET" ],
                "route": "/api/products/{id}"
            },
            "backendUri": "https://myservice.azurewebsites.net/api/items/{id}",
            "requestOverrides": {
                "header": {
                    "X-Original-Request-ID": "{headers.x-request-id}"
                }
            },
            "responseOverrides": {
                "statusCode": 200,
                "body": "{\"message\": \"Success for product {id}\"}"
            }
        },
        "staticResponseProxy": {
            "matchCondition": {
                "route": "/info"
            },
            "backendUri": "invalid",
            "responseOverrides": {
                "body": "This is static information.",
                "contentType": "text/plain",
                "headers": {
                    "X-Custom-Header": "StaticValue"
                }
            }
        }
    }
}

Understanding the Configuration

myApiProxy Example Breakdown:

• matchCondition:
  • methods: The proxy will only match GET requests.
  • route: Matches routes like /api/products/123. The {id} is a route parameter that can be used elsewhere.
• backendUri: The request will be forwarded to https://myservice.azurewebsites.net/api/items/{id}. The {id} from the route is automatically substituted.
• requestOverrides:
  • Adds a new header X-Original-Request-ID to the forwarded request, taking its value from the incoming request's x-request-id header.
• responseOverrides:
  • Sets the HTTP status code to 200.
  • Replaces the response body with a JSON string. The {id} here refers to the route parameter.

staticResponseProxy Example Breakdown:

• matchCondition:
  • route: Matches requests to /info.
• backendUri: Set to invalid because this proxy returns a static response and doesn't need to call a backend.
• responseOverrides:
  • Provides a static response body.
  • Sets the Content-Type header.
  • Adds a custom header.

Route Parameters and Transformations

You can reference route parameters from the matchCondition.route in both backendUri and responseOverrides using the format {parameterName}.

You can also perform more advanced transformations using Liquid templating. For instance, to access request headers, you can use {headers.headerName}.

Common Use Cases

• API Gateway: Expose a single entry point for multiple microservices.
• URL Rewriting: Present cleaner or more user-friendly URLs.
• Request/Response Transformation: Adapt requests/responses for different clients or backend systems.
• Static Content Serving: Serve static files or simple responses without writing a full Function.

Limitations

While powerful, proxies have some limitations:

• Proxies are purely configuration-based and don't execute custom code directly. For complex logic, you'll still need Azure Functions.
• Limited capabilities for complex request/response manipulation compared to writing code.

For more detailed information and advanced scenarios, refer to the official Azure Functions Proxies documentation.