A protocol for calling AWS Lambda functions in the cloud from an HTTP context.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


HTTP Function Protocol

A protocol for calling AWS Lambda functions in the cloud from an HTTP context.

See the current version of the Specification.


AWS Lambda Functions can be invoked from many AWS services. What is missing is an easy-to-use model to call them from an HTTP context. This protocol defines a way to invoke Lambda functions from an HTTP context.


At this time there is a Lambda Proxy in Node.js that implements the HTTP Function Protocol and a PHP script that invokes a lambda function.

Why from an HTTP context?

The modern web consist of static resources like images, text documents etc. and dynamic resources like shopping carts, search results etc. Static resources are easy to host today with you favourite web hosting service or AWS S3. Scaling is not difficult, as caching, CDNs and the scalability of S3 offer easy-to-use solutions.

Dynamic resources are a bigger challenge. Although many web hosting services offer at least PHP and sometimes other runtime environments for software, environment configuration and especially scaling are are difficult. AWS Lambda offers a solution to this problem, as scaling is built-in and the environment is so much abstracted that environment configuration is basically limited to selecting the right amount of memory and limiting maximum runtime for a function call.

Since the Web is basically stateless - as are Lambda functions - they are a good match for deploying dynamic resources.

What about API Gateway?

AWS proposes to invoke Lambda functions from the API Gateway. This works, but is not entirely practical. Configuring a Lambda invocation is tedious, as API Gateway is basically a UI for setting up REST services. This requires a lot of boilerplate configuration to handle things like HTTP headers. Returning arbitrary status codes in the response is even more complicated to set-up as the mapping mechanism between the Lambda function output and the configured error code is convoluted.

Looking at the configuration options of popular webservers like Apache or Nginx, one can easily see, that a lot of implicit configuration (ETags, index pages, error handling, ...) happens, which lets the webserver behave as a webserver even if the user uploads only an index.html. This is missing from API Gateway and for good reason, since REST services have different conventions.

But the biggest challenge is that the URL space of many websites evolves implicitly by the documents that are available on the server. This together with the powerful URL-manipulation facilities of webservers (server-side and client-side redirects and URL rewriting) can not easily replaced with the API Gateway.

How does the HTTP Function Protocol help?

The HTTP Function Protocol defines clearly how an HTTP request and its metadata is made available to the Lambda function. It also defines how the Lambda function returns an HTTP response.


Is there an implementation of the HTTP Function Protocol?

At this time an implementation exists as a proxy: Lambda Proxy. The Lambda Proxy should be used behind a webserver like Apache or Nginx and allows this webserver to send requests to a Lambda function.

How do I write a Lambda function that is compatible with the HTTP Function Protocol?

That is quite easy. For input you can rely on a simple and well-defined data structure in the event. For output you need to return a simple and well-defined data structure. Both data structures are very close to the HTTP context in which the function is invoked.


At this time, three things would help to make the HTTP Function Protocol more useful:

1. A webserver module for Nginx and/or Apache

The available proxy implementation requires a separate process behind the webserver. Implementing the HTTP Function Protocol directly in the webserver would make the webserver the only component that is necessary to use AWS Lambda.

As Lambda functions are invoked via well-defined HTTP requests, implementing such a module should be possible with limited effort (the AWS request signing method may require a bit of work).

The configuration directives for Nginx could look like this:

location /lambda/invocation {
  # required
  lambda_region eu-west-1;
  lambda_function do-something;

  # optional
  lambda_qualifier '42'; # default is ''
  lambda_parameters '{ "parameter": "value" }'; # default is {}
  lambda_scheme 'http'; # default is $scheme
  lambda_host example.com; # default is $host
  lambda_body 'variable=value'; # default is ''

  # available to Lambda function without configuration: $method, $uri

  # caching: similar to proxy_cache_* directives

####2. A proxy implementation in PHP Many web hosting services allow their customers to upload PHP scripts. This could be leveraged to let them access AWS Lambda functions from PHP.

####3. A cloud webserver in AWS Running a full website in AWS today requires a webserver somewhere (e.g. in an EC2 instance) to orchestrate the requests to different services. Sometimes this is the only thing that runs on this instance and delegates requests to S3, Lambda etc. That makes it expensive to run, especially when the number of requests fluctuates, and difficult to scale because an instance does not scale by itself (either switching to bigger instances or loadbalancing between multiple instances is required). The ideal solution would be to upload a webserver configuration file and let AWS handle everything else.