Note: this is part 2 in a 2 part series. Please click here for part 1 (running Go in an AWS Lambda).
5. Setup API Gateway
Login to your AWS account, and navigate to API Gateway.
1. Create a new API:
2. Name the API:
3. Add & configure the resource:
Make sure to check ‘Enable API Gateway CORS’. This will result in API Gateway automatically setting up an OPTIONS method with basic CORS configuration allowing all origins, all methods, and several common headers. You can manually add more strict rules to this at a later stage.
4. Create & configure the HTTP GET method for the resource:
Point the method to the Lambda function created in Part 1.
Grant the method permissions to access your lambda.
5. Setup the GET Parameters in the Method Request:
All of the parameters that are setup here can be passed into the final URL of the endpoint. In the next steps these will be mapped to the Lambda.
6. Setup the Integration Request & Template Mapping:
Next is where the JSON object is specified that is passed into the Lambda function as the eventJSON. In the integration template the request parameters can be accessed by using $json.params(‘paramName’).
In our case, the first two parameters width & height are mapped as integers, and the second 2 parameters are mapped as string.
For more details on API Gateway mapping templates, have a look here.
7. Setup the Method Response:
This is where all the possible HTTP response codes are defined. In case of our barcode generator endpoint, we only return 200, 400 & 500.
For the 200 status we need to define 2 response headers: Allow-Access-Control-Origin & Content-Type. Content-Type is required so that the API Gateway method integration can map the Lambda base64 encoded image response to the correct image Content-Type: image/png.
8. Setup the Integration Response and Binary Conversion:
It is important to set ‘Content Handling‘ to ‘ CONVERT_TO_BINARY ‘.
Do not define a mapping template. When you do not define a mapping template, API Gateway invokes the passthrough template to return the Base64-decoded binary blob as the image file to the client.
API Gateway converts results into binary content if:
- The result content type matches one of the pre-configured binary content types, and
- The response content handling is set to ‘CONVERT_TO_BINARY’.
To add binary support for the content type, you need to add the content-type in the ‘Binary Support‘ section:
9. Add integration responses for the 400 & 500 error codes:
When provided with an error regex, API Gateway will map the Lambda error responses to the correct HTTP method response statuses.
10. Testing with a correct / incorrect payload:
That looks good – the endpoint is returning the correct status code, content-type and binary data:
When using a bad request payload, we get a 400 status code, with a JSON error response.
11. Deploy the API and get the URL to invoke your endpoint:
We now have our Invoke URL, and can append this with ‘/barcode‘ plus our request parameters. This URL can be used as the source of an image:
https://41xevk8avc.execute-api.us-east-1.amazonaws.com/Production/barcode?message=testing&width=200&height=200&type=qr
– OR –
[html]
<img src="https://41xevk8avc.execute-api.us-east-1.amazonaws.com/Production/barcode?message=testing&width=200&height=200&type=qr" alt="QR Code"/>
[/html]
And we are done! To summarise, you now have an understanding on how to:
- Write golang functions for AWS Lambda.
- Use AWS API Gateway to return binary content.
- Link together AWS Lambda & API Gateway to create a scalable HTTPS service for barcode generation.
If you would like to setup a custom domain name for the URL of the endpoint – for example have something like:
https://api.myprettyurl.com/barcode
You can do so by following the steps in this article.
Please leave your comments. I would love to hear if any of you were able to create some other cool web-services using the techniques explained in this article.
