POSTing Binary or Multipart Form-Data to an API in Amazon API Gateway

Do you have a need to upload a file to an API endpoint in API Gateway? Whether you need to HTTP POST a binary or a text file to an API, a.k.a., multipart form-data, this article will explain how to accomplish this.

The way to do this is to define multipart/form-data as a binary media type for your API & proxy the payload directly to a Lambda function. From there you can parse the body to get your file content using libraries available to parse multipart data (parse-multipart in Node.js for example).

The steps are as follows:

  1. Go to Settings for your API in API Gateway.
  2. Add multipart/form-data to the binary media types section.
  3. Add Content-Type & Accept to the request headers of your proxy method.
  4. Add the same headers to the integration request headers.
  5. Redeploy the API.

See Enabling binary support using the API Gateway console for even more detailed steps.

Remember that there are size limits at every step of this process. API Gateway won’t take more than 10 MB & Lambda won’t go over 6 MB. So this solution is fine for smaller files, but not suitable for larger files.

An alternative solution is to not use API Gateway for your uploads at all & instead use a signed S3 URL to upload the file directly to S3. You can then process the file from S3 using Lambda. See Generate a presigned object URL using the AWS SDK for Java & Uploading objects using presigned URLs.