Building simple REST APIs in AWS using Lambda and API Gateway

Getting Started with API Gateway and REST

Introduction

This is a brief guide on how to set up and document a simple backend API in AWS, utilising API Gateway and Lambda.

What is REST — A Simple Explanation for Beginners, Part 1: Introduction

Configuring API gateway

The API endpoint is the gateway created to allow a user or application to gather and manipulate the information available via backend services.

Creating the actual API gateway is the first step, this should be done only once for an API (further endpoints and services will be added as methods).

1. In AWS API Gateway, create a new API using the ‘Create API’ button.
2. Select to ‘Build’ a ‘REST API’, which will give the most control over request and response configurations.
3. Choose to create a ‘New API’ and complete the below options:
4. API name: backend-services
5. Description: Enter a detailed description on what this API will do, who will use it and any limitations or parameters that could occur.
6. Endpoint type: Regional
7. Click ‘Create’.

Setting up the services

In this example, resources are created to act as an endpoint for each functional service, for example ‘users’ may be a service created to read, update and delete user details. Each service should have a resource, with optional sub-resources where additional options become available.

I.e. the user management service may follow the below resource tree:

Example resource tree. Source: Jack Johnson 2021

Although other configurations are possible, it is recommended for API sub-resource endpoints to be short and descriptive; the following format is common among API architectures:

Root(/) > Service (users) > Action (update) > Item (password)

Creating the resource

To create a new resource:

1. Select the resource that you want to create a child resource (this may well be root (/)).
2. Select ‘Actions’, then ‘Create Resource’ and complete the below options.
3. Resource name: users
4. Resource path (will convert spaces to hyphens): users
5. Create the resource by clicking ‘Create Resource).

Creating the method

A single non-parent endpoint should ideally consist of a single method (GET, POST, DELETE, PUT, etc.), this method should represent the action taken within the call:

GET = Select data

POST = Create new data

DELETE = Remove the data

PUT = Update the data

To create a new method:

1. Select the resource that you want to create a child resource (this may well be root (/)).
2. Select ‘Actions’, then ‘Create Method’.
3. On the newly appeared drop down option, select the method to set up (e.g. GET).
4. Select the tick to the right to confirm, or the cross to cancel.
5. On the configuration panel, complete the following options: Integration type: Lambda Function, Use Lambda Proxy integration: Check, Lambda Region: eu-west-2 (London), Lambda Function: <lambda-function-name>, Use Default Timeout: Check
6. When asked about giving permission, copy the command from the pop up and accept the warning.
7. Run the AWS CLI command copied (replacing ${stageVariables.environment} with the environment acronym) to give API Gateway permission to the function.

Setting up environments

By creating environment (stage) variables, we can enable cost effective, secure and autonomous functionality across multiple environments, monitoring the environment cost using these variables. The variables can also then be used within our Lambda functions.

To deploy the API:

1. Under the API navigation sidebar, select ‘Resources’.
2. Create a new stage by selecting ‘Actions’, then ‘Deploy API’.
3. Complete the following options in the modal: Deployment stage: [New Stage], Stage name: dev
4. Select ‘Deploy’ to complete the deployment of the API and create the initial stage (environment).

Authentication

Usually, authorisation is performed using AWS Cognito (user entity is created as part of our example app’s onboarding journey). The pool is connected to the endpoints that need authentication by modifying the Method Request.

As Authentication with Cognito can seem complex, I may cover this off in a different article. This API will still work without Authentication configured; however, it will be insecure, you have been warned!

Deploying the API

Deploying the API to an environment is relatively easy.

When environments are deployed, their configuration and operation becomes static for the given deployment, so changing the endpoints and configuration of the API after deployment doesn’t affect the environment until redeployed.

Navigate to the API Gateway console. For the API:

1. Under ‘Resources’, select the Actions menu.

2. Under ‘API Options’, select Deploy API.

3. Select the deployment stage you want to deploy: e.g. dev

4. Write a description of the changes made as part of this deploy.

5. Click ‘Deploy’.

The API gateway console will then display the API gateway URL that has been provisioned for this API, by using this URL using cURL or in an application like Postman, you can test and utilise these API endpoints.

Note: This is an updated version of an article that I originally wrote in 2017.