Kirill Zonov

Amazon Lambda + API Gateway introduction

December 06, 2017 | 12 Minute Read

Hi everyone, I just started AWS Learning Sessions in the company, I’m currently working in, and want to share with you our first lesson. We have built small Lambda function, named Greeter, and integrated it to the AWS API Gateway. If you want to get started with this tools and get some hands-on experience - this article will help you.

In Babbel we hire (backend, frontend, fullstack, infrastructure) :) and also use AWS a lot. Our infrastructure there is complex and solid, but still, there are some people, who don’t work a lot with it. F.e. frontend engineers, mobile developers, data analysts, they shouldn’t have AWS hands-on experience for everyday work, but even if it’s not required it’s a nice-to-have skill and so we started these sessions.

Currently, we introduced three lessons:

  1. Lambda + API Gateway,
  2. First lesson + DynamoDB and IAM Roles,
  3. First and second lessons implemented using Terraform, also we will need Swagger here.

The first session is just passed, so I going to share it with the world :)

AWS Lambda

You probably heard the buzzword “serverless”? Here is a quote from Martin Fowler’s blog: “Serverless architectures refer to applications that significantly depend on third-party services (knows as Backend as a Service or “BaaS”) or on custom code that’s run in ephemeral containers (Function as a Service or “FaaS”), the best-known vendor host of which currently is AWS Lambda. By using these ideas, and by moving much behavior to the front end, such architectures remove the need for the traditional ‘always on’ server system sitting behind an application.”  Why use it? The general idea is that you pay only for resources, which you are really using. You never pay for your infrastructure, when it’s idle. You invoked a function - you pay some small fraction of a cent. This makes much sense, because your app becomes a de-facto microservice-like. And you may require some parts of your application to be invoked constantly (let’s assume items information microservice in an e-commerce website), but some will be needed just a few times a day (newsletters dispatching in the same e-commerce website). You still can configure this imbalance using more/less powerful instances for your microservices, but there is still no need to keep the whole newsletter microservice sitting idle almost all the time. Obviously, it’s just a synthetical example, but the idea should be clear. Another cool thing is that AWS Lambda (and others) provides you auto scalability (to thousands per second) and high availability. Let’s say that on our e-commerce site we sell goods, related to Star Wars, LotR, GoT and other popular films/series. Usually, we have 1000 visitors per day, because people buy Darth Vader masks for their friends’ birthdays, or on another occasion. But Christmas and New Year are coming, and Black Friday and all that events, which will make our website to be visited by 10000-50000 persons per day! It’s already not a huge deal if we use cloud infrastructure. AWS EC2 or Heroku instances can be scaled easily. But still, you will need to manage it manually and to know, when to increase and decrease resources (to be fair, with EC2 it’s already possible to scale automatically). If most of your architecture is in Lambdas - you can just rely on it, it can be scaled automatically by invoking it from once per week, to 1000 per second. And good to know is that lambda starts in a container. You can specify RAM needed from 128MB to about 1.5GB. Currently, it supports Node.js, Java, C#, and Python. So, unfortunately, you cannot use Ruby to write your functions, but it’s no biggie since your functions will be pretty small and you won’t need to maintain complex internal architecture.

 Lambdas can be used/invoked in three different ways:

  1. As a backend to an API Gateway endpoint;
  2. Directly from an app with AWS SDK (can be invoked from both frontend and backend parts);
  3. As a callback for some AWS service, like S3 or DynamoDB.

API Gateway

As it should be clear from the name - it’s an api gateway ? To understand, what is AWS API Gateway it’s better to first understand, what is a VPC. VPC (Virtual Private Cloud) is a virtual network, which is isolated from other user’s of the cloud provider and from the outside world, and servers in VPC have an access to all of the AWS internal resources, like S3, DynamoDB, EBS etc. And now imagine it as a closed military city with all the facilities inside, like barracks, kitchen, and warehouse. And the API Gateway in this analogy will be a checkpoint - entrance. So it can provide external apps a RESTful access to your VPC. I find this analogy very colorful and precise.

Construction time (Lambda)

I told you that you’ll have hands-on experience with AWS Lambda today, so have at it! I assume you already have an AWS account and can start playing around with it. So first you should go to the AWS Lambda chapter in AWS Console.

select aws lambda in the console

push create function

basic aws lambda settings

When you will be on the Lambda function creation screen - you will have to specify some basic config options:

  1. Name. Pretty obvious field.
  2. Runtime. My example will be implemente using Node.js, because I have hands on experience with it, so please choose it as well.
  3. Role. Choose "Create new role from template(s). If you read my post some time after it had been written, probably some naming changed, because AWS keeps evolving, but the idea should still be the same.
  4. Role name. This field will appear after you selected the Role option. This field is also should be clear to you.
  5. Policy templates. Because we are building very basic lambda function - just choose default template and then needed policies will be added automatically when we will need it. You should choose here Basic Edge Lambda permissions.

Then push “create”, it will take up to couple of mintes (because it also goes via AWS Lambda xD) and then your function will be created. It’s funny that when I made a workshop, the interface was different, then now, so as I said, don’t be confused if you have another appearance :)

newly created lambda function

We are currently interested in Function code block. Here you have very basic code, but it’s already can be tested. First, few words about structure of the function.

exports.handler = (event, context, callback) => {
    // TODO implement
    callback(null, 'Hello from Lambda');

Handler is a function, which Lambda will invoke to execute your code. So it should be an entry point. Actually you can give it another hame, just don’t forget to put it also into the Handler input field above the code block. Lambda handler expects three params, event, context, callback. “Event” is an object containing external params your Lambda use to pass vars/data to your function. F.e. our query/body params from a request will be passed here. “Context” is a runtime information. For instance, when the function will be terminated by timeout, CloudWatch log groups, Cognito identity. “Callback” - you use it to return information to your caller. First param of it is an error, last is a result. As you see in the example above, first param is null, so it means that no error had been invoked. Let’s try to test it! Push the Test button above:

click the test button

It will ask you to configure a new test event:

configure a test event

Don’t change anything there, just press create, it will be created and you’ll be back on the previous screen. Tap Test again there. Great it works!

successful test

Funny thing is that AWS changed it’s hello world function, but didn’t change hello world test event. So you could notice on my screenshot, that by default we have some params passed to the function, but don’t use them in the code. Don’t worry, we will change it anyway :)

Construction time (API Gateway)

 Go into Services -> API Gateway. Then click on the button Create new API, and you will end up on the following page:

api gateway creation page

All options should be selected as in my screenshot.

empty gateway

So here is our brand new API Gateway, let’s make it real! Click Actions -> Create Resource.

aws api gateway creation

No need to select any checkbox, just add your resource name “greeter”. After that you need to click again on Actions, then Create method, select Get there and create it. Then you will see following page:

api gateway method creation

Here are fields you need to select:

  1. Integration Type. As it's obvious - Lambda Function. If you use a backend server, you may want to use HTTP, if you want to test your comprehensive gateway - you may choose Mock, but for our lesson, you need exactly Lambda Function.
  2. User Lambda Proxy Integration. Select it. It means that the whole request object will be passed to your function and you can work with it directly together with building the response. This is a cool new feature, so I encourage you to use it.
  3. Lambda Region. It may be tricky for you to remember it, but you can find it on the same page in the browser address line. Choose it for Lambda Region, I bet it's the same as API Gateway region.
  4. Lambda Function. This input appears after selecting the Lambda Region. Here you should be able to find your lambda function. If there is no your function - you probably have chosen the wrong region, try another.
  5. User Default Timeout. Just use the default option here.

Click Save, it will ask you to automatically give a new IAM Role permission, just click OK, because it’s OK. Voila! It’s almost ready! Let’s try to test our shiny new gateway!

test api gateway

Don’t pass any params on the next screen, just push Test. Baaaam, doesn’t work, you should get such result:

  "message": "Internal server error"

Time to go back to your Lambda Function and change it a little bit:

exports.handler = (event, context, callback) => {
    callback(null, {
        statusCode: '200',
        body: "Hello, " + event.queryStringParameters["name"] + "!"

Here in our function, we return a callback, which has no error, but the response is actually an HTTP response object. As you see, you can pass a status code and a body. I think the code is pretty straightforward, so no need to explain it. We are close to the finish line! Go back to your API Gateway, click the Test button, you will again be on this page:

aws api gateway test lambda

pass Query Strings param name=Yourname and press Test. On the right part you should get the response from your API, that it greets you by name =) It isn’t hard, is it? The last thing is to really deploy your API. Bear with me, it’s just couple of clicks!

Click to Actions button above your API endpoints list and just select Deploy API from there. You will get a small dialog window, just enter a new stage name (usually it will be staging or production) there and click deploy:

select api stage

Yay, here is a link to your deployed API:

deployed API Gateway

You can click on it, but it will open with an error because you don’t have a root action. So to actually get your desired result, add a path and a param there, like: That is it! Just to recap, now you have a complete knowledge, not only about how to create a new Lambda function, but also about how to create an API Gateway, point it to a Lambda and how to deploy it as well! So the post is huge, but I hope you’ve got a new knowledge from it :)