Your First Serverless API in Ruby with AWS Lambda & API Gateway

Florian Stagliano
Nov 5 · 5 min read

In this article, we are going to build a random-quote-generator as a serverless API, using Amazon Web Service’s AWS Lambda and API Gateway.

A short Introduction to AWS Lambda and API Gateway

AWS Lambda is an on-demand, serverless computing service, that runs a function in the cloud in response to specific triggering events. Triggers can be other cloud services, or an HTTP request hitting our API.

As a so-called serverless or function-as-a-service (FaaS) solution, the AWS lambda function sits on the server as a file, while AWS is looking for trigger events. When the event occurs AWS allocates (or spins up) the resources required for the computation and executes the code. Consequently, there is no dedicated server running in the background and resources are only used while the process is running.

Since November 2018 Ruby was added as a supported language for AWS lambda. As AWS Lambda provides support for inline code edit, so we don’t need any special tool for that. Great.

AWS Lambda will do the actual computing work of our API.

For the API “Frontend” we are going to use the AWS API Gateway, which is Amazons all-round serverless HTTP solution.

API Gateway will be the “front door” for our AWS Lambda function, acting as an intermediary between the client and our code. It handles the incoming client HTTP request (by authorizing, validating and transforming it), before handing it over to the targeted application on AWS, in this case, our lambda function. It then receives the response of the function, transforms and prepares the response, before sending it back to the client.

Let’s break down the setup process in steps.

Step 0 — Sign Up to AWS

If you don’t already have an account, first you’ll need to set one up with AWS. Here is a great guide on how to create and activate an AWS account. They offer a free tier to experiment with a large variety of their services.

One note: The verification of your account can take between 5min and 24h. So better sign up in advance, before you want to start the tutorial!

Step 1 — Setting up the Lambda Function

Sign in to your AWS account, click on the “Services” tab and select “Lambda” in the “Compute” resources.

Choose Lambda under Compute resources

On the Lambda dashboard, click on create “New Function” and select “Author from Scratch” to create a simple “Hello World” template. Type in a name for your function and select “Ruby 2.5” under “Runtime” as the environment. Proceed with clicking on the button “Create function”.

Creating a new Lambda Function

You should see now a green border on the top of the next screen, confirming that the setup was successful. Great!

Next, we have to add a test event by clicking the “Test” button on the top right of the console. Select an “Event Name” for your test and accept the default values. Back at the Lambda dashboard, click the test button to run the test event. It should show a green bar stating “Execution result: succeeded” at the top of the page. Perfect! The words “Hello world from Lambda” should appear in the body of the response (see bottom of your dashboard).

Step 2 — Adding our code

We can now add our functionality to our code. In our case, we want to add the following simple, logic to the lamda_handeler method.

Each function call should generate a random number, which is used to select a quote from an array of quotes by using the generated number to select a single element of the array.

Since we selected Ruby as the runtime environment we can implement this logic using Ruby syntax:

Define an array “quotes”, with your favorite quotes, with a string for each quote as an array element. Next, define a variable “random_number”, which will generate a random number based on the size of the array (taking into account the 0-notation of the array!).

The quotes array and number variable have to be defined within the lambda handler function. The output is defined within the body part of the response as shown below.

Code for our random-quote-generator

Step 2 — Setting up the API

As a next step, we want to make the function callable from a user from the “outside”, which means we have to add a “trigger” event and linking the trigger event to the API Gateway.

To do so let’s click “add trigger” on the lambda page, and select “API Gateway as the “Trigger configuration”. We select “Open with API key” under “Security” so that only users with the API authorization key are able to access the API. Clicking on “Add API Gateway” creates the link to our Lambda function.

Setting up the API Gateway as the trigger for our Lambda function

Back at the Lambda menu, we can see how the Lambda function and API Gateway are connected now. The URL for the endpoint and the required API key for access are displayed at the bottom of the page.

Lambda Function connected to API Gateway as a trigger for execution

Step 3 — Testing the API in Postman

Since we decided to make the API only accessible via an API key we will need to access the API via Postman.

After signing in, we choose “New” at the top left of the screen to create a basic GET request. We are asked to select a name and a folder to save the new request.

Creating a new request in Postman

Back at the main menu, we need to enter the end-point URL in the GET field of our request. In the “Authorization” tab we have to enter “x-api-key” as the key and our API Key as the value. These have to be added to the “Header” section via “Add to” > “Header”. Finally, let’s test our setup, by pressing “send”.

Input parameters for testing our API in Postman

After a second the ”Body” tab at the bottom of the screen, shows the response proving that our random-quote-generator as a serverless API in AWS is working. Well done!

I hope you enjoy the article and got curious to further explore the world of serverless applications.

Florian Stagliano

Written by

Former Aircraft Design Engineer and Theatre Production Manager, Software Engineer in the Making

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade