Shenanigans of Serverless- part 1

shardul aeer
Feb 5 · 14 min read

Serverless computing with its massive scalability and low cost is the next big thing for the cloud. The devil however lies in the details, as I discovered while working on some of projects. This article focuses on Lambda, the flagship serverless offering by AWS. Lambda has intricacies and hard limits which can throw up real challenges unless some clever design principles are adopted.

1. 30 second API timeout

A popular use case of Lambda is for building APIs. Here Lambda is paired either with API gateway for REST or AppSync for GraphQL. While Lambda can have a maximum timeout of 10 minutes, both of these impose hard limits of 29 and 30 seconds respectively. Hard limits cannot be increased, period. Exceed the timeout period and your call fails with an error response.

To overcome this limitation one should allocate more memory to a Lambda or opt for an asynchronous pattern.

Solution- Asynchronous Lambda invocation

Here API gateway immediately returns a 200 response and asynchronously invokes the Lambda function.

This approach suits an invoke and forget approach. However a lot of complexity arises if the client seeks a definite response from Lambda:

Asynchronous invocation and polling.

A disadvantage of the above approach is that results can only be received sequentially. To overcome this, you may make the first call synchronous and pass a unique identifier to the user. The user polls for each result with help of this unique identifier.


API gateway console

Under HTTP headers add the following

Name: X-Amz-Invocation-Type
Mapped from: method.request.header.InvocationType

Here the user must pass ‘InvocationType: Event’ as header for asynchronous invocation, otherwise this will by default will lead to synchronous invocation.

To make the endpoint asynchronous only set mapping as ‘Event’(in quotes) and skip the next step.

We can have asynchronous by default invocation by hardcoding ‘Event’ in X-Amz-Invocation-Type. Image credits:

2. In Method Request

Add ‘InvocationType’ under HTTP Request headers. Basically user enters the ‘InvocationType’ header which is mapped to ‘X-Amz-Invocation-Type’. This tells API gateway whether the all is synchronous or asynchronous.

Add ‘InvocationType’ header to method request

2. 10 MB data limit

Again, this is a hard limit imposed by API gateway. For files below 10MB we can enable binary inputs from settings.

Enable binary inputs for API gateway by adding the required MIME type in settings. This works for files upto 10MB only

Beyond 10MB we need to use a service like S3 for uploads. But this means we need more than one API calls. The approach depends on the service you want to develop:

Brief working

<?xml version="1.0" encoding="UTF-8"?>
<CORSConfiguration xmlns="">

2. Create IAM role with S3 write permissions. Generate the access key and key secret. Basically we create a signed URL using this IAM role to give temporary S3 write access to the client..


3. Use the Keys in your Lamba function to generate signed URL

Generating PUT signed URL with Javascript SDK

4. Return pre-signed URL to user on first API call. User uses it for uploading files.

5. User makes second API call. Perform processing on data and return response.

For more details please read Sam Quinn’s article on S3 uploads.

Returning large files

The 10MB limit also applies while sending data out of API gateway. Again we will use S3.

We need to take some security measures here. You may not want unauthorised users to access the file in case they get hold of the S3 item URL. This again adds a lot of complexity.

3. Lambda vs Lambda-proxy integration

Again this is related to API gateway.


For a detailed comparison please read Lakshman Diwaakar’s article here.

Simple enough? Now lets look at the shenanigans:

Also the nomenclature could’ve been better, because both variants are REST APIs over HTTP protocol.

HTTP API- announced in Re:Invent 2019
The existing REST API

2. Monolithic vs multiple lambda functions: Lambda proxy integration opens up a new design pattern where all calls are routed into a single, monolithic lambda function. A single Lambda handling multiple requests will theoretically stay warmer and reduce cold starts. This pattern is simpler to implement, for example one could fit a full fledged Flask or Express server inside a single lambda.


The trade offs for this approach also have to be considered. Serverless Hero Yan Cui makes a strong case for using single-purpose Lambda functions. Putting all your code together will affect capability discovery, debugging and scaling of your Lambda functions. Further if your Lambda takes high volumes of incoming calls, the cold start benefit will start to diminish. This is because of the way Lambda works, i.e. a new instance is spawned every time when existing instances are busy and a new call is received. Ultimately its a trade off between simplicity and performance.

3. Using Lambda-proxy integration? Be prepared to write more code. The asynchronous invocation feature I wrote about earlier will have to be developed by yourself.

4. Using Lambda integration? The next heading is for you.

4. Data input formats

This is related to how API Gateway accepts data and passes it to Lambda. API gateway has first class support for query strings, path parameters, headers and JSON data. However other MIME types like ‘x-www-form-urlencoded’ and ‘multipart/form-data’ are second class citizens.

a. application/json

Here JSON data is passed through the request body. API gateway performs some transformations on the data and passes it to Lambda in JSON format.

{ Name : 'John Smith', Age: 23}

If we select Lambda integration, we perform these transformations in API gateway itself. This is done with help of the Velocity Template Language(VTL).

According to Wikipedia

Apache Velocity is a Java-based template engine that provides a template language to reference objects defined in Java code. It aims to ensure clean separation between the presentation tier and business tiers in a Web application (the model–view–controller design pattern).

Lambda integration may be unsuitable if this is not your primary use case. Proxy integration may be a better bet for users unfamiliar with Java based templating.

An example VTL template. Proxy integration may be a better bet for users unfamiliar with Java based templating.

In Lambda proxy you perform transformations and templating in Lambda itself. Here API gateway transforms the request body, headers, path and query parameters, metadata etc into a JSON object and passes it to Lambda.

Lambda proxy event example. Do note that if our input body is in JSON format, here the “body” field will contain the exact JSON input.

b. application/x-www-form-urlencoded

Here the body of HTTP message sent is essentially a giant query string. name/value pairs are separated by the ampersand (&), and names are separated from values by the equals symbol (=).

x-www-form-urlencoded example body in Postman.

Here the Non-alphanumeric characters are replaced by `%HH’, the two hexadecimal digits representing the ASCII code of the character.

Here’s where the fun begins. API gateway can accept input in any form, Lambda accepts only JSON format. However API gateway provides no simple way to convert ‘x-www-form-urlencoded’ into JSON.

Conversion of ‘x-www-form-urlencoded’ string to JSON can be done in two ways:

We’ll see both the methods in action here. Let the encoded input body be as follows:


2. Lambda integration: A VTL template from stack overflow for x-www-form-urlencoded seems to be popular among serverless community. Basically it converts your string into JSON and passes the value to Lambda.

Lambda handler and VTL template for x-www-form-urlencoded

Go to integration request section in API Gateway and add the above mapping template. Be sure that content type is set as application/x-www-form-urlencoded, not application/json.

Integration request mapping

Now lets look at the results

One of the values for ‘key1' has disappeared

Here we had passed two values for key1, however we get back only one. The template keeps the latest value for each key and discards others (‘first’ discarded). Besides the template is hacky at best. Surely there must be a way to fit multiple values in an array using VTL, but at the time of writing I could not find such code in the public domain. If you are able to sneak it out of Pentagon, do let us know in the comments.

Here’s what an AWS official wrote on the Amazon Web Services Forum:

there is no direct support for parsing “application/x-www-form-urlencoded” parameters from the body. If you want to parse parameters from your POST body, you would need to parse them using a mapping template.

An alternative would be to send the entire payload to your lambda function and parse the key value pairs from within your lambda function.

How about not using ‘x-www-form-urlencoded’ at all? The issue is that HTML cannot produce JSON on its own. HTML forms can produce only ‘x-www-form-urlencoded’ , ‘multipart/form-data’ or ‘text/plain’. We need to use Javascript to produce JSON, which may force changes on your client side.

While it may tempting to go with the API Gateway’s default JSON option for building your API, this may force you to change your web front end design. Here’s a detailed comparison of which format you prefer and when. It’s worth noting that Stripe and Twilio, two popular API providers stick to ‘x-www-form-urlencoded’ for requests.

We can have a compromise here. The request body can be directly passed into Lambda. The VTL template can take care of query and path parameters. But if that’s not the case we should stick to Lambda proxy or HTTP API.

API gateway handles path and query parameters. ‘x-www-form-urlencoded’ string is passed to Lambda.
x-www-form-urlencoded’ request body sent to Lambda without transformation

Binary payload with application/x-www-form-urlencoded

A major advantage of x-www-form-urlencoded is the ability to send binary data. That is to say, it allows files to be encoded sent through an HTTP requests. Binary data is not supported by JSON. We can send binary data less than 10MB in size to Lambda using API gateway.

Locate settings in the left hand side menu

2. Add the MIME type you wish API Gateway to support. To allow all formats, enter the following:

Add ‘*/*’ to support all MIME formats

While sending binary data remember to add ‘Content-Type’ header containing the MIME type you wish to support.

Lambda proxy method

Response template for lambda proxy integration

It is important to take note of ‘isBase64Encoded’ property. This should be set as true if we have enabled binary media support, even if the response body contains textual data. Otherwise we get back a binary encoded string for both binary and text data. ‘isBase64Encoded’ by default is set to false. Note that ‘isBase64Encoded’ is not a header but a flag for API Gateway.

‘a2V5PXZhbA==’ is binary for ‘key=val’. Here I had not added ‘isBase64Encoded’ property. Its value by default is false.

Rather than set it manually, we can directly take its value from the API Gateway event.

Lambda returns back data in exact same format. ‘isBase64Encoded’, Content-Type header and event body are taken from the event itself.
No body returned. ‘isBase64Encoded’ is false or is not set.
‘isBase64Encoded’ is true

Remember to add ‘Content-Type’ header containing the MIME type you wish to support.

Lambda integration method

This one is again is nuanced. There are two ways to do it:

Enter exact MIME type, e.g. ‘image/png’ not ‘*/*’ like we did earlier

2. The description for binary Media support is self explanatory.

API Gateway will look at the Content-Type and Accept HTTP headers to decide how to handle the body.

Earlier the Content-Type header was enough. Now we need Accept header as well. Both hold the same value, that is name of the MIME type. This in our case is image/png.

3. Our mapping sends the request body directly into Lambda.

Route input to Lambda
Set ‘Content-Type’ as your MIME type

4. Lambda function simply returns back the data it received without any change.

Return data without modification

5. Make the request

‘Content-Type’ and ‘Accept’ headers set as ‘image/png’
PNG image sent in binary encoded format. We get back the image we sent.

But what when setting file headers is not possible? This can happen when the POST message contains data of a different format or when we make a GET request. The proxy integration discussed earlier will work properly, but Lambda integration method will need modifications. We need to add the MIME type headers manually using API gateway.

Enter exact MIME type, e.g. ‘image/png’
Go to method response (step 2) and then integration response (step 3)

2. In method response add a new response header ‘Content-Type’.

Content-Type’ response header added

3. In integration response map ‘Content-Type’ header to the correct MIME format, which in this case is ‘image/png’ (with quotes). Set ‘content handling’ to ‘Convert to binary’.

Map ‘Content-Type’ header to the correct MIME format with quotes. Set content handling to ‘Convert to binary’.

Here we hardcoded ‘image/png’ into the header mappings. Alternately we could make Lambda pass the required header map it as follows:

In this method the JSON returned by Lambda also contains the header. This means you need to add a mapping for body as well. To simplify things I hardcoded the header mapping with ‘image/png’.

The Lambda function in this example returns an image stored in an S3 bucket. Lambda converts the image into a Base64 encoded string. API gateway converts this into Binary format and adds the correct header.

Lambda reads image from S3 and converts in into a Base64 encoded string


In this case I used GET, but any other method can also be used. As no headers need to be set, this can work from a web browser as well.

A drawback of

x-www-form-urlencoded drawbacks

This format is good for textual data and small files. There’s a second MIME format supported by HTML forms to address the issues facing ‘x-www-form-urlencoded’ format.

c. multipart/form-data

‘multipart/form-data’ is the format of choice for transmitting large files. It allows both text and multiple files to be sent together. This is achieved by separating each item using a string boundary.

Each (key, value) pair is encoded as follows

Content-Disposition: form-data; name="<<field_name>>"

So for two values we get

----------------------------024892011799986865440046\r\nContent-Disposition: form-data; name=\"key1\"\r\n\r\nvalue1\r\n----------------------------024892011799986865440046\r\nContent-Disposition: form-data; name=\"key2\"\r\n\r\nvalue2\r\n----------------------------024892011799986865440046--\r\n

The boundary value is automatically generated but we can also manually assign it using the ‘Content-Type’ header:

Content-Type: multipart/form-data; boundary=--------------------------632614546983522473131640

API gateway does not support ‘multipart/form-data’. But we can pass the request body to Lambda and parse it from there. However this too has caveats, and I found that all these solutions only support Proxy integration.

2. High level frameworks like Flask or Express could be used. But they require Proxy integration and can be an overkill for a small function.

3. Use a Lambda middleware framework like Middy.js. This approach too requires proxy integration and can bloat your function. I couldn’t find an equivalent library for Python.

It seems that NodeJS has a better module ecosystem for Lambda compared to Python and other languages.

d. Other exotic content types

From these examples 3 patterns to handle MIME types have emerged:


From the various nuances discussed here, it is clear that Serverless computing is not simple as shown to be. Issues which may be trivial for a regular server may require heavy lifting in serverless.

Part 1 was about challenges arising from hard limits imposed by API gateway upon Lambda. Part 2 will focus on the specifics of Lambda itself. Stay tuned and do not forget to follow!

Want to be friends? Or looking to hire a developer? Catch up with the writer on LinkedIn.

The Startup

Medium's largest active publication, followed by +581K people. Follow to join our community.

shardul aeer

Written by

Backend developer and serverless enthusiast. Be hooked for something amazing.

The Startup

Medium's largest active publication, followed by +581K people. Follow to join our community.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade