|
| 1 | +# How to Pass a File Type through API Gateway |
| 2 | + |
| 3 | +API Gateway now allows for the passing of binary media types (i.e. files). In this document, we will be showing you how to pass through a PDF file. |
| 4 | + |
| 5 | +First create an API in API Gateway by clicking the "Create API" button in the top left of the screen and following the instruction to name and create the API. |
| 6 | + |
| 7 | + |
| 8 | + |
| 9 | +After that, under the API name on the left side of the screen, click on settings. |
| 10 | + |
| 11 | + |
| 12 | + |
| 13 | +From there, you can add all files to the accepted binary media types by adding `*/*` (we are allowing the API to accept all file types and can validate elsewhere such as in the Lambda function itself). |
| 14 | + |
| 15 | + |
| 16 | + |
| 17 | +Next, we need to link up our Lambda function to an API Gateway Resource. Create a resource by going to the Resources section under the API name on the left side of the screen, click on the "Actions" dropdown menu and select "Create Resource." |
| 18 | + |
| 19 | + |
| 20 | + |
| 21 | +Name your new resource and click "Create Resource". Next, select the new resource created, click the "Actions" drop-down menu again, and click "Create Method." |
| 22 | + |
| 23 | + |
| 24 | + |
| 25 | +A dropdown field will appear below the resource. Click on the field and select "POST". A "POST" section will appear below the resource. |
| 26 | + |
| 27 | + |
| 28 | + |
| 29 | +Clicking on the "POST" section will provide you with the setup page to the right. Under Integration type select Lambda Function. Click the checkbox for Use Lambda Proxy integration. Under lambda region, select your AWS region (for MK it will be us-west-2). Once that is entered, another field will appear asking for the Lambda Function you will be connecting to the resource. If you have already made a function, enter the name and click Save. |
| 30 | + |
| 31 | + |
| 32 | + |
| 33 | +Now, let’s take a look at our Lambda function we are linking to our API method. |
| 34 | + |
| 35 | +```javascript |
| 36 | +module.exports.handler = function(event, context, callback) { |
| 37 | + |
| 38 | + const response = { |
| 39 | + statusCode: 200, |
| 40 | + body: '' |
| 41 | + }; |
| 42 | + |
| 43 | + callback(null, response); |
| 44 | +}; |
| 45 | +``` |
| 46 | + |
| 47 | +This is a simple function for binary events. All binary event functions should have at least these two keys in the response: |
| 48 | + |
| 49 | + { |
| 50 | + statusCode: ###, |
| 51 | + body: '' |
| 52 | + } |
| 53 | + |
| 54 | +There are two other keys that may be required in the response for more complex requests. These are: |
| 55 | + |
| 56 | + headers: {}, |
| 57 | + isBase64Encoded: true/false. |
| 58 | + |
| 59 | +To check if this is working with a real PDF, download and open Postman. While you are doing that, grab the URL of the method in API Gateway. First deploy the API by going to the Resources section, clicking the "Actions" drop-down button and selecting "Deploy API." |
| 60 | + |
| 61 | + |
| 62 | + |
| 63 | +Select the Deployment stage. If there is none, create a new deployment stage and name it "prod." |
| 64 | + |
| 65 | +After the API has been deployed, go to the Stages section under the API name on the left side of the screen, click on your new deployment, click on your resource, and click on the POST method. |
| 66 | + |
| 67 | + |
| 68 | + |
| 69 | +From there, grab the URL on the top of the new window. |
| 70 | + |
| 71 | + |
| 72 | + |
| 73 | +Back in Postman, change the request to POST and input the URL provided by API Gateway you just grabbed above, go to the Body tab, select the form-data input, change the key to be a file type, and browse to choose your PDF test file. If you are not sending the PDF through a form, you can simply use the binary input option. |
| 74 | + |
| 75 | + |
| 76 | + |
| 77 | +Press on the "Send" button in the top right. The response field should be empty. If there are any errors, they would show up in here. Some common errors I found while testing were 403: Missing Authentication Token, which means your URL is probably incorrect or 502: Internal server error, which means your Lambda function is probably not correct. |
| 78 | + |
| 79 | +To check if the PDF is actually being sent through, we can check the Cloudwatch logs. In the Cloudwatch service, click on the Logs section on the left side of the screen and choose the lambda function you have been using. |
| 80 | + |
| 81 | + |
| 82 | + |
| 83 | +After that, click on the latest log stream which will be the first log on the top of the list. |
| 84 | + |
| 85 | + |
| 86 | + |
| 87 | +In this log you will see all of the events that occured while running this lambda function. In one of the events you can see that the PDF file is being passed through. |
| 88 | + |
| 89 | + |
| 90 | + |
| 91 | +If you have not made an S3 bucket yet, make one now. In the bucket, you will have to change the permissions to make the bucket public. To do this, click on your bucket in the S3 service, click on the permissions tab, click on the Bucket Policy section, and copy the following code into the IDE: |
| 92 | + |
| 93 | +(Please refer to the document "[AWS - Using Lambda to transfer file between buckets](https://docs.google.com/document/d/1awH_pgaMtY9g7kJUtBUNPY3ZCCmZJcdO--Z7Fr5lZ-o/edit)" for a more detailed explanation of how to set up buckets, if needed.) |
| 94 | + |
| 95 | + |
| 96 | + |
| 97 | +```json |
| 98 | +{ |
| 99 | + "Version": "2008-10-17", |
| 100 | + "Statement": [ |
| 101 | + { |
| 102 | + "Sid": "PublicReadGetObject", |
| 103 | + "Effect": "Allow", |
| 104 | + "Principal": "*", |
| 105 | + "Action": "s3GetObject", |
| 106 | + "Resource": "arn:aws:s3:::<bucket name goes here>/*" |
| 107 | + } |
| 108 | + ] |
| 109 | +} |
| 110 | +``` |
| 111 | + |
| 112 | +Now that we know the PDF is successful being passed through API Gateway and we have our S3 bucket setup, we need to parse the file data back to being usable so we can send it to S3 from the Lambda function. For this we will use a Node.js package called Busboy. We need to update our Lambda function as follows: |
| 113 | + |
| 114 | +```javascript |
| 115 | +const AWS = require('aws-sdk'); |
| 116 | +const s3 = new AWS.S3(); |
| 117 | +const busboy = require('busboy'); |
| 118 | + |
| 119 | +exports.handler = function(event, context, callback) { |
| 120 | + |
| 121 | + const response = { |
| 122 | + statusCode: 200, |
| 123 | + body: '' |
| 124 | + }; |
| 125 | + |
| 126 | + let bb = new busboy({ headers: event.headers }); |
| 127 | + console.log(bb); |
| 128 | + bb.on('file', function (fieldname, file, filename, encoding, mimetype) { |
| 129 | + console.log('File [%s]: filename=%j; encoding=%j; mimetype=%j', fieldname, filename, encoding, mimetype); |
| 130 | + |
| 131 | + s3.upload({ |
| 132 | + Bucket: '<bucket name goes here>', |
| 133 | + Key: filename, |
| 134 | + Body: file |
| 135 | + }).promise().then(function() { |
| 136 | + callback(null, response); |
| 137 | + }); |
| 138 | + }) |
| 139 | + .on('field', (fieldname, val) => { |
| 140 | + console.log('Field [%s]: value: %j', fieldname, val) |
| 141 | + }) |
| 142 | + .on('finish', () => { |
| 143 | + console.log('Done parsing form'); |
| 144 | + callback(null, response) |
| 145 | + }) |
| 146 | + .on('error', err => { |
| 147 | + console.log('failed', err); |
| 148 | + callback(err) |
| 149 | + }) |
| 150 | + |
| 151 | + bb.end(Buffer.from(event.body, 'base64')); |
| 152 | + console.log('event.body', event.body) |
| 153 | +}; |
| 154 | +``` |
| 155 | + |
| 156 | +This code uses Busboy to parse the incoming file. The .on is an event listener which recognizes when a file is present and executes certain commands. Busboy outputs a stream that we can use to upload to S3 by using the s3.upload function seen above. By the time Busboy ends, the file will be in the S3 bucket specified. |
| 157 | + |
| 158 | + |
| 159 | +If the Lambda function is not setup properly, you may experience a PDF being saved into the S3 bucket, but when opened is blank. With a little refactoring, the PDF will show. |
| 160 | + |
| 161 | +Now we must grab the S3 URL of the newly imported file so we can reference it later in a database, we can build the URL using the basic AWS S3 web link and the information we already have. It will look something like this: |
| 162 | + |
| 163 | +```javascript |
| 164 | +let url = 'https://s3-us-west-2.amazonaws.com/' + s3Bucket + '/' + s3Key; |
| 165 | +``` |
| 166 | + |
| 167 | +We have to update the Lambda function very slightly to build this URL. Add in and update the few missing variables in the given URL above. |
| 168 | + |
| 169 | + |
| 170 | +If you are submitting the information through a form and you have other non-binary data that needs to be parsed out, we can do this by updating the "field" portion of the Busboy function. The way I did it was to define jsonObject and jsonComplete as empty objects outside of the Busboy function. After that you can make changes to the "field" portion like so: |
| 171 | + |
| 172 | +```javascript |
| 173 | +// ... |
| 174 | +.on('field', function (fieldname, val) { |
| 175 | + jsonObject[fieldname]=val; |
| 176 | + let url = 'https://s3-us-west-2.amazonaws.com/' + s3Bucket = '/' + s3Key; |
| 177 | + jsonObject.resume = url; |
| 178 | + jsonComplete = { |
| 179 | + statusCode:200, |
| 180 | + body: JSON.stringify(jsonObject) |
| 181 | + }; |
| 182 | +console.log('JSON', jsonComplete); |
| 183 | +}) |
| 184 | +// ... |
| 185 | +``` |
| 186 | + |
| 187 | +This essentially will iterate every time the function sees an event key. The jsonObject[fieldname]=val; line is creating a new JSON object key every iteration and assigning all of the keys to be the correct name and, therefore, the correct value. |
| 188 | + |
| 189 | +The next two lines about the URL will add in the S3 reference that the PDF file created to the JSON object so you can store the reference with the rest of the information. |
| 190 | + |
| 191 | +The jsonComplete object is giving API Gateway an OK response and stringifying the newly completed JSON. After this, add a line in the `.on('finish')` section to `callback(null, jsonComplete)` to get the desired output. |
0 commit comments