Parameterized GET API using AWS API Gateway and AWS Lambda
Ever wondered how convenient life would be without the hassle to setup a server every time you need to deploy a project? Well with AWS Lambda, you can do that and much more! According to AWS official documentation, AWS Lambda is an event driven, server-less computing platform provided by Amazon as a part of Amazon Web Services.
In this post, I will talk about:
1. Creating an AWS Lambda
2. Writing a simple Python code that accepts an integer and makes a call to numbersapi.com to get a trivia about that number.
3. Fire up an API Gateway using AWS console.
4. Hooking the API to the lambda function and making a test GET request.
Let’s go through each step.
Step 1: Creating a Lambda
To create a Lambda function, navigate to your AWS console and under Lambda service [Link], select “Create a new function”.
Choose the first option “Author from Scratch” and get ready to fill in the details
Name: Let’s give our function a name. I call my function lambda_test
Runtime: For the sake of this article, I will choose Python 2.7
Note: I chose a much older version of Python because the use of botocore library is depreciated in Python 3.x versions. Since we will be needing the requests module to make request to numbersapi, we need the botocore module to import requests. An alternative way (if you plan on using Python 3.x )will be to download the libraries on your machine, and create a .zip file along with the python code and upload it to Lambda
Don’t bother about setting the permissions yet and hit “Create function”
Step 2: Writing the Python code
The simple function mocks an REST API style definition. It checks if the given argument exists and is an integer and makes a request to numbersapi.com using that integer. The response, essentially a trivia about that number is returned to the user.
A few things to note about the structure of function in Lambda, we need a handler which gets invoked every time the function is called. Every handler has two mandatory parameters i.e. event and context . The event parameter is a python dictionary used to pass data to the function whereas a context parameter provides various information about the lambda function during the execution like: time remaining for function termination, CloudWatch log group and stream etc. For the sake of this article, we will pass our arguments directly into the event dictionary.
Once done, click “Deploy”. Our final lambda function will look something like this:
Time to write a test case and check our function! Click on the arrow next to the “Test” button and configure a new test case. Choose the hello-world event template and write a small test as follows:
Once we run our test case, we will be able to see the response (a trivia for number 15).
Step 3 & 4: Setting up API Gateway
We created a Lambda function alright. But how do we invoke this function from outside world? We need a “front-door” to reach the function. In comes AWS API Gateway. Amazon API Gateway is a fully managed service that makes it easy for developers to create, publish, maintain, monitor, and secure APIs at any scale. Using API Gateway, you can create RESTful APIs and WebSocket APIs that enable real-time two-way communication applications. API Gateway supports containerized and serverless workloads, as well as web applications.
Head over to the API Gateway service in your AWS console. For this tutorial, we will create a REST API.
Select “New API” from the radio buttons. give your API a name and keep the endpoint as “Regional” for now.
Create the API and you will land on the “resources” page of the created API Gateway. Go through the following steps:
- On the “Actions” dropdown, click on “Create Method”. For now, as we are using only “GET” method for our function, select it. Then, click on “Tick Mark” on the right side of “GET” to go through its setup.
- Choose Lambda Function as “Integration Type”
- Choose the region where we created the function earlier
- Write the name of the Lambda Function we created
- Save the method where you it will ask for confirmation of “Add Permission to Lambda Function”. Agree on that and we are done.
You will have a GET method card in your resource pane now. Head over to that method and you should see the method execution flowchart like follows:
This flowchart describes the life-cycle of a request when issued by a user. Since our Lambda function expects user to pass a number, we will take the input as GET request parameter. To do this, head over to the “Integration Request” tab and scroll down to find “Mapping Templates”.
What is a mapping template?
API Gateway uses mapping templates to transform incoming requests before they are sent to the integration with backend. You can define one mapping template for each possible content type. The content type selection is based on the Content-Type header of the incoming request. If no content type is specified in the request, API Gateway uses an application/json mapping template. Mapping templates use Apache Velocity to generate request for the backend.
Create a new application/json type mapping template. You will be asked for securing integration before you can proceed. Click yes and scroll to mapping editor. Define a new mapping as follows:
The mapping template specifies to pluck the “keyword” query parameter from the URL and assigns it to the event parameter “keyword” for the Lambda function to process. To learn more about syntax for mapping template, refer to the documentation.
All done! Now the only part left is to deploy the API and test it out. Back on the “resources” page, select “Deploy API” under “Actions”. You will be prompted to set a deployment stage. With API Gateway, you can set multiple deployment stages like dev/uat/qa/prod. For now, we will set the stage to dev. Select [New Stage] and assign stage name as dev. We can leave the descriptions for now.
Once you hit “Deploy”, you will be redirected to the “resources” page and will find an “Invoke URL”. Click on that to open your API in the browser.
You can now test the API by appending a URL parameter (URL + ?keyword=<some_integer>) . If you enter a valid integer, you will get a trivia related to the integer on your screen!
That’s all for now folks! In next posts, I will go over some other AWS services like DynamoDB and S3 bucket and how to connect with them. Stay tuned and feel free to drop comments if any confusion, suggestions, anything constructive.
