APIs with Lambda + API Gateway

Learn to build a serverless API using AWS Lambda and API Gateway!

Introduction

⚡️ 30 second Summary

In this project, you'll learn to build an API without having to manage traditional servers. Say hello to AWS Lambda and Amazon API Gateway!

This project is most ideal for roles like Backend Developer, Cloud Architect, or Systems Engineer, where it's important to understand how to set up serverless architecture and manage APIs.

In this project, get ready to...
  • ⚙️ Develop a serverless Lambda function.
  • 🚪 Configure an API with API Gateway.
  • 🔌 Connect Lambda with API Gateway.
  • 💎 Write JSON documentation for your API.
Three-Tier Architecture

This is also the SECOND project of an awesome three-tier architecture series.

Three-tier architecture splits applications into three essential layers: presentation, logic, and data.

In this project, you're diving into the logic tier, which is all about your app's backend. This is where you write and run the code that translates user actions (e.g. button clicks) to application functionality (e.g. website searches or data processing).

We'll talk more about this architecture in later projects - for now, let's focus on Lambda and API Gateway. Make sure to follow the rest of this series to build up a fully functional three-tier solution! 🚀

Want a complete demo of how to do this project, from start to finish? Check out our 🎬 walkthrough with Natasha 🎬

If you're up for a bit of a challenge, quiz yourself on the key concepts up ahead in this project.

This project is part of a series:

  1. Part 1: Website Delivery with CloudFront
  2. Part 2: You are here!
  3. Part 3: Fetch Data with AWS Lambda

Before we start Step #1...

It's always good to understand exactly what you're here to do.

Create a Lambda Function

In this step, we'll create a Lambda function.

The function will fetch data from a database and return it to the user. This is a very common use case in web apps.

For example, when a user searches for a product in an online shop, the website's backend needs to query the product database, find the relevant product, and send its details back to the user's browser as swiftly as possible.

In this step, get ready to:

  • Create a new Lambda function.
  • Configure its settings.
  • Add some code to retrieve user data.

Navigate to the Lambda service

  • Log in to the AWS Management Console as your IAM Admin user.
  • Make sure you're in the AWS region closest to you.
  • Head to the Lambda console.

What is AWS Lambda?

AWS Lambda is a service that lets you run code without needing to manage any computers/servers - Lambda will manage them for you.

Lambda runs your code only when you need it to (so you're not paying for any idle time).

It also scales automatically, from a few requests per day to thousands per second - all you need to do is supply your code in one of the languages that Lambda supports.

Create a new Lambda function

What is a Lambda function?

A Lambda function is a piece of code that you run in AWS Lambda.

You write Lambda functions to do things like process data, respond to events, or run automated tasks.

  • Select Create a function.
  • Select Author from scratch.

Configure the Lambda function

  • For Function name, enter RetrieveUserData.
  • For Runtime, select a runtime using Node.js.

What does runtime mean?

The runtime is like the environment where your code lives and runs.

While you write code in a programming language, the runtime provides the actual environment where that code runs. For example, Python code needs a Python runtime environment.

Selecting the right runtime for your AWS Lambda function makes sure it has everything (i.e. dependencies) needed to run efficiently.

💡 What is Node.js?

Node.js is a popular JavaScript runtime environment.

Traditionally, JavaScript is used for scripts that run right in your web browser, handling tasks like animations and form validations. This browser-based setup means all the JavaScript action happens on your device after the web page loads.

But with Node.js, you can take JavaScript to the server side. Now, you're running scripts on a server before anything even reaches the browser.

This is a big deal because it lets developers use JavaScript for both frontend and backend tasks, which makes development much more efficient. You can use Node.js to build things like server-side apps, command-line tools, or even chat with databases using JavaScript.

In our case, we're using Node.js to create the backend for a web app.

  • For Architecture, select x86_64. This selects the type of processor the function will run on. Most use cases are fine with x86_64.

What does architecture mean?

Architecture refers to the type of hardware (specifically, the processor) that your AWS Lambda function uses. By selecting an architecture, you're making sure that your code runs efficiently and is optimized for the specific processor it will run on.

x86_64 is a widely-used architecture in many computers and servers.

💡 Woah, did you just say hardware? I thought Lambda is serverless

Even though AWS Lambda is serverless, which means you don't have to manage any servers or worry about the infrastructure, it still runs on physical servers behind the scenes.

Even though you're not directly handling the hardware, you still need to select an architecture that AWS manages for you.

  • Select Create function.
  • Success!

What's in my Lambda function's page?

The Lambda function's page in the console shows you everything about your function - its code, configuration settings like memory and timeout, and metrics on how it's performing.

We'll use it to add our function's code next.

Add the code

  • Scroll down to the Code source panel.
  • Copy and paste the following code into the code editor, replacing YOUR_REGION with your actual AWS region (e.g., 'us-west-2'):
// Import individual components from the DynamoDB client package
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, GetCommand } from "@aws-sdk/lib-dynamodb";

const ddbClient = new DynamoDBClient({ region: '[[YOURREGION="enter your region"]]' });
const ddb = DynamoDBDocumentClient.from(ddbClient);

async function handler(event) {
    const userId = event.queryStringParameters.userId;
    const params = {
        TableName: 'UserData',
        Key: { userId }
    };

    try {
        const command = new GetCommand(params);
        const { Item } = await ddb.send(command);
        if (Item) {
            return {
                statusCode: 200,
                body: JSON.stringify(Item),
                headers: {'Content-Type': 'application/json'}
            };
        } else {
            return {
                statusCode: 404,
                body: JSON.stringify({ message: "No user data found" }),
                headers: {'Content-Type': 'application/json'}
            };
        }
    } catch (err) {
        console.error("Unable to retrieve data:", err);
        return {
            statusCode: 500,
            body: JSON.stringify({ message: "Failed to retrieve user data" }),
            headers: {'Content-Type': 'application/json'}
        };
    }
}

export { handler };

What does this code do?

This code sets up a Lambda function that retrieves data from a DynamoDB table.

It looks for specific user data based on a 'userId' and returns that data. If there's an error e.g. the userId doesn't exist in the database, it returns an error message.

Note: We haven't set up the DynamoDB table or userID yet - those will come in the next project!

  • Check: Make sure you've updated the placeholder region YOUR_REGION to your own region code.

Deploy the function

  • Select Deploy. This saves your code and makes the function ready to use.
  • Check for the Deployment successful in the bottom right corner of the console.

Great work! You've just set up a Lambda function.

Set up API Gateway

Now that we have our Lambda function ready, we need a way to access it. This is where API Gateway comes in.

What is an API?

An API, or Application Programming Interface, is a way for different software systems to talk to each other. It's like a messenger that carries requests and responses between systems.

In this project, we're creating an API that carries requests from your user's browser to your Lambda function.

In this step, get ready to:

  • Create a new API in API Gateway.
  • Configure the API's settings.

Navigate to API Gateway

  • In the AWS Management Console, head to the API Gateway console.

What is Amazon API Gateway?

Amazon API Gateway is an AWS service that makes it easy for developers to create, publish, maintain, monitor, and secure APIs at any scale.

It manages incoming traffic, directing them to the correct services, and makes sure only authorized requests get through.

💡 What is the relationship between APIs and Lambda?

API Gateway acts as the "front door" to our Lambda function. It receives requests and then forwards them to Lambda functions for processing.

Lambda processes the request, then sends the response through the API Gateway back to the user.

💡 Why do we need the API Gateway?

Directly exposing Lambda functions to user requests isn't best practice, because Lambda doesn't have built in security or API management features.

API Gateway brings in authentication and authorization features, and advanced API management capabilities (e.g. request routing) that make your app more efficient.

Create a new API

  • Scroll down the list of available API types.

What are the different API types?

API Gateway supports different types of APIs, like REST, HTTP, and WebSocket. Each type is suited for different use cases, whether it’s maintaining a standard web API (REST), providing real-time capabilities (WebSocket), or routing requests (HTTP).

  • Find REST API.

What is a REST API?

A REST API (Representational State Transfer) is type of API that uses HTTP methods to interact with resources (more on HTTP methods later in this step).

REST is popular because it's simple and can be used with virtually any programming language. We're using a REST API today to set up an API that connects the user with your Lambda function.

  • Select Build.

Configure the API

  • Under API details, select New API.
  • For API name, enter UserRequestAPI.
  • For API endpoint Type, select Regional.

What are endpoint types?

Endpoint types define the scope of your API's availability. Regional endpoints are accessible within a specific AWS region, which is great for localized applications because it has low latency for clients in that region.

💡 What are the other endpoint types?

Besides Regional, there are Edge-Optimized (for global applications) and Private (for internal networks) endpoints.

Each serves different needs depending on how and where you want your API accessed.

  • Select Create API.

Nice work setting up that API! The API will be the front door to our Lambda function, letting users access the function via HTTP requests.

What's in my API's page?

Your API’s page in the AWS Console provides a dashboard view of your API, including its methods, deployments, and settings. It's the central hub for managing and monitoring your API.

So good, that's the API Gateway set up.

To start using the API, we need to figure out how we can make requests to the API Gateway...

Set up an API Resource

In this step, we'll create an API resource.

Resources are like the different sections or pages of your API. They help organize how your API handles different requests.

In this step, get ready to:

  • Create a new resource in your API.

Create a resource

  • Under Resources, select Create resource.

What are API resources?

API resources are individual endpoints within your API that handle different parts of its functionality.

For example, an API for a messaging app might have separate resources for retrieving messages and for retrieving user profiles.

  • For Resource name, enter users.

What are resource path and resource name?

A resource path is the URL path used to access that resource, e.g. /messages for retrieving messages and /users for retrieving user profiles.

The resource name is used in the API Gateway to refer to that resource, helping you manage and reference it easily in the console.

  • Select Create resource.
  • Select the /users resource.

Woohooo! We're getting really close now. Great work creating the API resource.

Since a resource can be used for many different kinds of actions, we'll need to define what each of those actions are.

Set up an API Method

To round off our API's setup, let's create an API method. Methods are things you can do with a resource.

For example, you can use a GET method to retrieve data, a POST method to create data, a PUT method to update data, and a DELETE method to delete data. The list goes on!

In this step, get ready to:

  • Create a GET method for the users resource.
  • Connect the GET method to your Lambda function.

Create a method

  • In the Methods panel, select Create method.
  • Select GET from the Method type dropdown.

What are methods?

API methods define the actions you can perform on a resource.

They are based on standard HTTP methods, which are different commands that let you interact with data over the internet. For example:

  1. GET to retrieve,
  2. POST to add,
  3. PUT to update, and
  4. DELETE to remove data.

Configure the method

  • Select Lambda Function for the Integration type.

What are integration types?

Integration types are the backend services that can fulfill an API request. This setting determines how API Gateway passes the request data to the backend and processes the response.

By selecting a Lambda function as the integration type, API Gateway can directly call your AWS Lambda function each time someone uses an API endpoint:

  1. When API Gateway gets a request, it sends it directly to your Lambda function.
  2. Your Lambda function takes care of the request, processes it, and sends the result back to API Gateway.
  3. API Gateway passes that response on to the user.
  • Switch on Lambda proxy integration.

Extra for Experts: What is a Lambda proxy integration?

Lambda proxy integration is a setting that simplifies the connection between API Gateway and Lambda.

Normally, when the user interacts with the website, a request (e.g. a request for data from a database) goes straight to the API Gateway. This request contains multiple parts, like headers, query parameters, path parametres and more.

The API Gateway has the massive task of breaking down the request and reformat it in a way that the Lambda function can process. Once Lambda returns a response (e.g. retrieved data from the database), API Gateway needs to map the response back into a format expected by the client.

With Lambda proxy integration, API Gateway doesn't need to reformat the user's request. Instead, it passes the entire request - headers, query parameters, path parameters, and body directly to Lambda. The Lambda function itself will have to be capable of processing the request internally.

  • For the Lambda function, make sure the default region selected is where you've created your function.
  • Select your RetrieveUserData function.

Why do I select a Lambda function?

The Lambda function you select will be the function that gets triggered when that API method is called.

In this case, when the GET method for the /users resource is called, API Gateway will pass that request to the Lambda function you set up. When the function runs, Lambda will retrieve user data in a DynamoDB table.

  • Select Create method.
  • Method created!

Method done = API setup DONE! 😮‍💨

That's great, we'll just need to deploy our API and see it in action.

Deploy your API

Finally, let's deploy our API. Deploying makes our API accessible through a public endpoint, so we can actually start using it.

It's like publishing a website - once it's deployed, anyone can access it!

In this step, get ready to:

  • Deploy your API to a new stage.

Deploy the API

  • Select Deploy API.
  • For Stage, select New stage.

What does stage mean in Lambda?

In API Gateway, a stage is a snapshot of your API at a specific point in time.

API Gateway lets you deploy different versions of your API to different stages. This way, you can easily control who accesses what version of your API and when.

Usually, developers work on new features or changes in a development stage of the API, test new features in the testing stage, then deploy in in the production stage.

  • For Stage name, enter prod.

Why is the stage called prod?

Prod stands for production.

Production is the live environment where your API is fully working, and there is live traffic and real users using the API too.

  • Select Deploy.
  • Deployment success!

What is on the 'prod' stage's page?

This page shows you settings, metrics, and logs for your API when it’s in production.

Visit your API

  • On the same page, find your prod stage's Invoke URL.

What is the invoke URL?

The invoke URL is the URL where your API can be used.

In real world scenarios, developers use the prod stage's invoke URL into their live application's code, so users are using the live/production version of the API.

  • Copy the Invoke URL.
  • Access the URL in a new tab on your browser.

Dang it - you'll get an error because we haven't set up our DynamoDB table yet. That's okay!

The API set up is all done, which means you've still learnt how to create a serverless API (how cool is that). We'll get to creating the DynamoDB table and connecting that with this API in the next project.

Secret mission

Welcome to your 🤫 exclusive 🤫 secret mission!

Your mission, should you choose to accept it, is to write documentation for your API in API Gateway.

💎 In this secret mission, get ready to:

  • Write documentation (in JSON!) for your API.
  • Publish and download your documentation.
  • Showcase more advanced skills with APIs in your project documentation. Stand out from the rest!

Showcase Advanced Skills

Delete your resources

Delete your resources

Now that we've tested our API, it's time to clean up the resources we created. This is important to avoid incurring unnecessary costs. It's like tidying up your kitchen after cooking - you don't want to leave a mess behind.

Resources to delete:

  • Delete the API in API Gateway.
  • Delete the Lambda function.
  • Delete the API
  • Navigate to the API Gateway service in the AWS Management Console.
  • Select your API (UserRequestAPI).
  • Select Actions and select Delete API.
  • Confirm the deletion.
  • Delete the Lambda function
  • Navigate to the Lambda service in the AWS Management Console.
  • Select your function (RetrieveUserData).
  • Select Actions and select Delete.
  • Confirm the deletion.

That's a wrap!

That's a wrap!

You've just built your first serverless API with Lambda and API Gateway!

You learned how to:

  • 🐑 Create and configure a Lambda function.
  • 🚪 Set up and configure an API in API Gateway.
  • 🧱 Create resources and methods within your API.
  • 🚀 Deploy your API to a live stage.

Ready to quiz yourself? You got this! 💪

Nice one - you've just set up the second tier of a 3-tier architecture!

Ready for the next two parts of the series?

p.s. Does it say "Still tasks to complete!" at the bottom of the screen?

This means you still have screenshots left to upload, or questions left to answer!

  1. Press Ctrl+F (Windows) or Command+F (Mac) on your keyboard.
  2. Search for the text Return to later.
  3. Jump straight to your incomplete tasks!
  4. 🙋‍♀️ Still stuck? Ask the community!