Http Functions

Routing

By default, when you create an HTTP triggered or WebHook function the function is addressable via a route of the form http://<yourapp>.azurewebsites.net/api/<funcname>. You can customize this route via the route property in your function.json file, e.g.:

{
    "bindings": [
        {
            "type": "httpTrigger",
            "name": "req",
            "direction": "in",
            "methods": [ "get" ],
            "route": "products/{category:alpha}/{id:int?}"
        },
        {
            "type": "http",
            "name": "res",
            "direction": "out"
        }
    ]
}

This function will be addressable via url http://<yourapp>.azurewebsites.net/api/products/electronics/123. This route also demonstrates support for route constraints. Documentation on the constraint formats supported can be found here.

In a C# function, you can then define parameters that bind to the route parameters like so:

public static Task<HttpResponseMessage> Run(
     HttpRequestMessage request, string category, int? id, TraceWriter log)
{
    ...
}

Here's the same function definition coded in Node.js, showing how the bound route parameter values can be accessed via context.bindingData:

module.exports = function (context, req) {
    var category = context.bindingData.category;
    var id = context.bindingData.id;

    ...
}

By default, all function routes will be prefixed with api. You can customize or remove that prefix entirely via the http.routePrefix property of host.json, e.g.:

{
    "http": {
        "routePrefix": ""
    }
}

Here we've set this to an empty string which means that no prefix will be used. So rather than https://<yourapp>.azurewebsites.net/api/<funcname> the default route for functions in the app will be https://<yourapp>.azurewebsites.net/<funcname>.

Authentication and Authorization

HTTP triggered functions support API key based authentication, where the API key is passed in one of the following ways:

• Query string: The key is passed as a query string parameter named code (e.g. https://<yourapp>.azurewebsites.net/api/<funcname>?code=<your api key>)
• Request header: Alternatively, you can pass your API key in a request header named x-functions-key

The following authorization levels are supported:

• Anonymous: No authentication is required. The function may be invoked without an API key.
• Function: Authentication is required and a function API key must be used.
• Admin: Authentication is required and the function can only be invoked with the admin (master) key

API Keys

API keys are may be defined at two distinct levels:

• Host: Also commonly referred to as Function App Level keys. Keys defined at this level apply to the entire Function App. You have the ability to define Function Keys at this level, and they would allow clients to authenticate against any function. This is also where your Master Key is defined.
• Function: Function level keys apply to the specific functions they're defined under, restricting its use for authentication to that function only.

To enable key rolling and consumer specific keys, you can define multiple named keys at the host and/or function levels.

API keys are persisted, encrypted, on the file system under D:\home\data\Functions\secrets, in files matching the function name for function level keys, and a file named host.json for the host level keys.

Master Key

The master key provides administrative access to the runtime APIs. You should exercise care if you choose to use the Admin authorization level for your functions as we do not recommend redistributing the master key.

WebHooks

For WebHooks, authentication and authorization are handled by the WebHook receiver for the WebHook type you've selected (e.g. GitHub, Slack, etc.). By default, the key that is provided to the WebHook receiver is the default function key (named 'default'). If you want to perform validation using a different key, the WebHook provider should provide a client ID (the key name) in one of the following ways:

• Query string: The client id is passed as a query string named clientid (e.g. https://<yourapp>.azurewebsites.net/api/<funcname>?clientid=<your key name>)
• Request header: Alternatively, the provider can pass the client ID in a request header named x-functions-clientid

NOTE: Keys defined at the function level take precedence over host level keys, so if a two keys are defined with the same name at the function and host level, the function key will be used.

Managing API keys

The primary way to manage API keys is through the Azure Functions portal.

In HTTP triggered functions, a key management panel is available in the portal, allowing you to manage (create, refresh and revoke) function and host level keys.

Key Management API

To support programmatic key management, the host exposes a key management API. API documentation coming soon.

Throttling

There are a few configuration knobs you can use to control throughput and concurrency for your http functions. By default, no throttles are in place - all requests that come to the Function App will be dispatched as in a normal Web App. Under extremely heavy load, depending on the details of your specific http functions you might find that request latencies start increasing to unacceptable levels, or you may notice other load issues based on resource utilization of your functions.

To provide some control over this, the following host level configuration knobs can be used, specified via the http configuration section in host.json. Note that these settings apply to each Function App instance not globally. These settings need to go inside an "http" section, and are:

• maxOutstandingRequests - the maximum number of outstanding requests that will be held at any given time. This limit will include requests that are queued but have not started executing, as well as any in progress executions. Any incoming requests over this limit will be rejected with a 429 "Too Busy" response. That allows callers to employ time based retry strategies, and also helps you to control maximum request latencies. Note that this only controls queuing that occurs within the script host execution path. Other queues such as the ASP.NET request queue will still be in effect and unaffected by this setting. The default is unbounded.
• maxConcurrentRequests - the maximum number of http functions that will be executed in parallel. This allows you to control concurrency, which can help manage resource utilization. For example, you might have an http function that uses a lot of system resources (memory/cpu/sockets) such that it causes issues when concurrency is too high. Or you might have a function that makes outbound requests to a 3rd party service, and those calls need to be rate limited. In these cases, applying a throttle here can help. The default is unbounded.
• dynamicThrottlesEnabled - When enabled, this setting will cause the request processing pipeline to periodically check system performance counters like connections/threads/processes/memory/cpu/etc. and if any of those counters are over a built in high threshold (80%), requests will be rejected with a 429 "Too Busy" response until the counter(s) return to normal levels. The default is false.

Note that these configuration settings apply at the Function App instance level (i.e. a single running host instance), not across host instances.