Azure Functions Proxies.json

Streamline your API management with Azure Functions Proxies.

Introduction to Proxies

Azure Functions Proxies is a feature of Azure Functions that enables you to create a thin API layer that forwards requests to your existing backend services. This allows you to decouple your clients from your backend services, abstract away complexity, and provide a consistent API surface. Proxies can be used for:

Proxies are configured in a file named proxies.json, which is located in the root of your Azure Functions project. Each entry in this file defines a proxy that maps an incoming request URL to a backend URL.

The proxies.json File

The proxies.json file is a JSON file that defines one or more proxies. It's an object where each key represents a proxy name. The value associated with each proxy name is an object containing the proxy's configuration.

Here's a basic structure:


{
  "proxyName1": {
    // Proxy configuration details
  },
  "proxyName2": {
    // Proxy configuration details
  }
}

Proxy Syntax and Properties

Each proxy object can include the following properties:

Property Description Required Type
matchCondition Defines the conditions under which the proxy should be invoked. Yes Object
backendUri The URL of the backend service to forward the request to. Yes String
requestOverrides Allows you to modify the incoming request before it's sent to the backend. No Object
responseOverrides Allows you to modify the response received from the backend before it's sent to the client. No Object
scaleResponses Determines if the proxy should scale the response based on client capabilities (e.g., content negotiation). No Boolean

matchCondition Properties

The matchCondition object specifies how to match an incoming request.

Property Description Required Type
route A route template that matches the incoming request path. Supports parameters enclosed in {parameterName}. Yes String
methods An array of HTTP methods that the proxy should respond to (e.g., ["GET", "POST"]). If omitted, all methods are matched. No Array of Strings

requestOverrides Properties

The requestOverrides object allows modifications to the request.

Property Description Type
method Override the HTTP method of the incoming request. String
headers An object of headers to add or override. Object
body The request body. Can be a string or a reference to a file. String / Object

responseOverrides Properties

The responseOverrides object allows modifications to the response.

Property Description Type
headers An object of headers to add or override. Object
body The response body. Can be a string or a reference to a file. String / Object

Request and Response Rewriting

Proxies are powerful for rewriting requests and responses. This is achieved using the requestOverrides and responseOverrides properties.

Parameter values from the route can be used in backendUri, requestOverrides, and responseOverrides by referencing them with %parameterName%.

Example: Routing and Parameter Substitution

This example creates a proxy that forwards requests for /api/products/{id} to a backend service at /api/v1/items/{id}, preserving the method.


{
  "getProductById": {
    "matchCondition": {
      "route": "/api/products/{id}",
      "methods": ["GET"]
    },
    "backendUri": "https://my-backend.azurewebsites.net/api/v1/items/%id%"
  }
}

Example: Modifying Request Headers

This proxy adds a custom header to the outgoing request.


{
  "addCustomHeaderProxy": {
    "matchCondition": {
      "route": "/api/data"
    },
    "backendUri": "https://my-service.com/data",
    "requestOverrides": {
      "headers": {
        "X-My-Custom-Header": "Proxied"
      }
    }
  }
}

Example: Rewriting Response Body

This proxy replaces the response body from the backend.


{
  "rewriteResponseBody": {
    "matchCondition": {
      "route": "/api/info"
    },
    "backendUri": "https://api.example.com/info",
    "responseOverrides": {
      "body": "{\"message\": \"Data successfully retrieved via proxy.\"}"
    }
  }
}

Advanced Features

File-Based Content

You can specify static content for requestOverrides.body or responseOverrides.body by referencing a file within your Function App project. For example, to use a file named default.html in the same directory:


"requestOverrides": {
  "body": "{default.html}"
}

This is useful for serving static files or default responses.

Conditional Logic (via Functions)

While proxies.json itself doesn't support complex conditional logic, you can achieve this by having a proxy forward requests to an Azure Function. The Azure Function can then implement complex routing or logic before calling the final backend service.

Request Aggregation

You can create multiple proxies that point to different backend services but share a common base path or are exposed through a single API gateway function, effectively aggregating them.

Best Practices