Your First API Gateway Endpoint Backed By Lambda
When it comes to creating a serverless API solution in AWS, there is not just one single solution. Imagine you could have your own Node Express application, which you could run in a Docker Container using Fargate. In this scenario, we manage no servers. In fact, because Fargate uses Docker containers, actually this opens us up to being able to literally run anything we can create a Docker image for. In the scenario we are discussing above, we still need to write code to build the API. Even though this would be a serverless solution, you are still building out the API part itself (using Express). API Gateway on the other hand is a serverless API solution itself, and combined with Lambda can be a completely serverless REST API. This article will help you establish an endpoint that we can hit from the public internet to invoke our Lambda function and give us some response back as a traditional API would.
API Gateway
API Gateway is an AWS service that boasts being able to handle up to 10,000 requests per second. If you are on the free tier you are able to make 1 million REST API calls and have 750,000 connection minutes free each month. API Gateway can have many different targets, but Lambda will be the topic of this article. Within Lambda, there are also two integration types. One is standard integration, and the other is the Lambda Proxy Integration. Lambda Proxy Integration passes through the body to the Lambda function and expects a specific type of response to be returned. Using this type of integration will disallow you from using mappings on the response either from the Lambda or to the user. These features are only allowed when Lambda is integrated in a standard way. I think the easy way to think about it is, if you need to do some sort of transformations, such as support an old API, or transform some key to something else, then the standard integration makes sense. If you want to use your Lambda as a handler would act on a more traditional REST API handler, with full control on how the response is returned directly in your Lambda, then the Lambda Proxy Integration would probably be a better choice. For this article, I will choose the Lamdba Proxy Integration type which is how the starter template we use will be set up.
Lambda
This brings us to AWS Lambda, which as a service, is like breaking code down into individual functions. These functions run in the cloud when they are executed. You only pay when the code is actually running. That is the big money saver compared to virtual machines which are running (and costing money) all the time, whether the code is running or not. If you only invoke your function 100 times a week, you are paying when your code is running. In addition, Lambda offers a generous free tier, up to 1 million invocations, and 400,000 GB-seconds of compute time per month. After that, you pay $0.20 per million requests, and $0.0000166667 for every GB-second of compute time. This is pretty cheap, and one reason why some people love lambda. Just to cover some high-level limits around Lambda. There is a built-in concurrency limit of 1000 per region. This is a soft limit and you can contact AWS to increase this limit. Also, a Lambda function can only run for a maximum of 15 minutes. This limit is slightly irrelevant for this article because API Gateway has a timeout of 29 seconds. For a long-running task, it should be performed in an asynchronous manner. In terms of language support, currently, Lambda supports Java, Go, PowerShell, Node.js, C#, Python, and Ruby code and if you want to use a different language there are custom ways you can create your own runtime.
Deploying An AWS Starter Template
The first place to start is to take advantage of one of the AWS starter templates. I highly recommend doing this when you are learning because even if you delete a lot of the code, seeing it, is what matters. It opens you up to potential new ideas and exposes you to things that can be done on AWS. No shame in generating a template and clearing it out and placing your code instead. In fact, I would call you smart because you are not wasting your time writing boilerplate code. With that said we will be using the AWS SAM Framework to generate our template and deploy it to the cloud. If you have never used the AWS SAM Framework, I recommend jumping over to another article I wrote on Building And Deploying Your First Lambda Function With The AWS SAM Framework. You do not need to complete the article, but it has a good introduction to SAM and getting it installed. With that part out of the way let’s run a few commands in our terminal to get ourselves started out. In a location of your choice let’s run sam init . We will choose AWS Quick Start Template, and then nodejs12.x. You can name your project as you please, but I will call it, api-gateway-demo. After the templates clone, we will choose the Hello World Example. Now you will want to cd into your project folder which has been created. This will be the name you gave your project. For me, I will run cd api-gateway-demo . Now we can run the following command.
After that completes, we need to run the following command.
The guided part of the command is to help guide us through the deployment parameters. I usually only do this the first time I deploy, and SAM will ask you if you want to save this configuration into a .toml file. If you select this option, the next time you deploy, you can simply run sam deploy and SAM will deploy with the parameters from this file. It makes deploys much quicker. When we run this command with guided we get some prompts to help us. First, you must name your stack, for mine, I will call it api-gateway-demo. Then you must choose your region, whichever region makes sense for you, I will be choosing to use us-east-1. Then we need to decide, do we want to confirm the changes before we deploy. When we make subsequent deploys, this means we would see a changeset and approve it prior to deploying. This is not necessary for this demo. We must also allow the CLI to create a role for us. We would not need this if we were manually creating a role and attaching it using the template.yml file. For the demo, we will allow the CLI to create the role for us, and generally, this is not the worst option. Lastly, we need to check whether we should save these settings in a .toml file. I would recommend selecting this as it improves deploy times going forward. Once all that completes, your template is uploaded and your template stack is created.
Testing Your Endpoint
AWS SAM creates Cloudformation stacks under the hood. Let’s navigate to Cloudformation in the region that you selected, and you should see your stack which has been created.
If you click on the stack name, we see an almost overwhelming amount of information on our stack. For now, we care about Resources. Clicking on that, we can see there were several things created for us. This includes a Function, a role for the function, permission for function, a REST API, a deployment, and a stage. Quite a few resources created for us to accomplish this, but if you wanted to do this through the console, you would need to create all these resources. Hence the reason, especially when you are starting out, it makes sense to use templates to start until you become more familiar with the AWS ecosystem. Let’s click on the Physical Id for the ServerlessRestApi Resource and find, Stages, in the left sidebar. Clicking on this reveals two stages created, and we will focus on the Prod stage. Unfolding the arrow next to the Prod stage, and then clicking on the GET method under /hello will reveal the invoke URL for our function. Go ahead and click it, which will invoke our lambda function and respond with the hello world response.
If this has worked for you then, congratulations, you have deployed your first API Gateway endpoint backed by Lambda. Now let’s customize it to do something more interesting.
Getting Repositories From Github
Now we want to make some small changes and be able to return the repositories, of a username on Github which is passed in as a query parameter. Let’s get started in the template.yml file with some clean-up and change some items to not just be boilerplate code.
The main changes in this file are around naming. I want an application that is named for what it is, and not hello world template names. By changing CodeUri it means we need to rename our folder from hello-world to repos. We removed some comments and Outputs since we were not using them. Lastly, we rename the resource itself for API Gateway to be /repos now instead of /hello. Now let's move to app.js and clean this up, as well as adding in some packages.
By default for this template, AWS has Axios as a dependency but commented out. We will use that as well as make some changes to the code, to fetch the repositories using a userid query string parameter being sent to our endpoint. Now we can run the similar commands as before starting with the below again.
Then because we saved our configuration to a .toml file we can simply run sam deploy . Once this completes, we can go back to API Gateway and refresh the page, and remember that each time we do sam deploy we are actually releasing a new stage. Now we can again click on Stages on the left-hand side and unfold the Prod stage. This time we no longer see /hello and should see our endpoint /repos instead. If we click on the GET method listed under it, we are then presented with an invoke URL. This time when we click the invoke URL we see nothing. Remember, our Lambda function is expecting us to pass a query parameter of userid . So let’s add that, in the URL of this new window, adding ?userid=YOUR_GITHUB_NAME_HERE . With that, you should be seeing your Github repos. Congratulations you have deployed your first customized endpoint which was backed by Lambda that does something for you in the cloud.
Clean Up
Before we conclude let’s clean up our resources. Since we are using a SAM template to deploy our code, the code is deployed as a Cloudformation stack. This is very convenient for clean up as we can simply visit Cloudformation in the console, click on our stack, and in the upper right-hand area click delete. It will ask you to confirm, and clicking delete stack will finalize the deletion.
Conclusion
API Gateway backed by Lambda is a no-brainer solution for applications who are unaware of what type of traffic they will receive, expect some sort of spikey pattern of traffic, or for a site that expects minimum traffic, it is practically free. The AWS SAM Framework presents us with a simple straightforward way to build serverless APIs backed by Lambda without dealing with the configuration aspect of things. These APIs can scale effortlessly to handling thousands of requests per second. Using these techniques to build serverless API solutions has never been cheaper or more efficient.
