This article teaches you how to create a serverless RESTful API on AWS. You will use CloudFormation to define the API Gateway in combination with Lambda to implement the functionality. DynamoDB is used to store the data. The example’s source code is available on GitHub and can be used to speed up your project.
If you are interested in defining the API in OpenAPI Specification or Swagger Specification read Create a serverless RESTful API with API Gateway, Swagger, Lambda, and DynamoDB instead!
If you are interested in deploying the API with the Serverless Framework read Create a serverless RESTful API with the Serverless Framework powered by API Gateway, Lambda, and DynamoDB instead!
API Gateway provides an HTTP API endpoint that is fully configurable. You define the HTTP resources (like
/user), the HTTP methods on that resources (like
DELETE, …) and the integration (e.g. Lambda function) that should be called to process the request. The Lambda function can then run whatever logic is needed to answer the request. API Gateway responds to the caller with the result of the Lambda function. The following figure demonstrates this flow.
If we zoom into the API Gateway component of the previous figure, we see what happens inside the API Gateway.
If you want to define a REST API you need to specify:
- Resources (e.g. GET /user)
- Methods on each resource (e.g. GET /user)
- Body Model
- Path parameters (e.g. GET /user/:userId)
- Query parameters (e.g. GET /user?limit=10)
- Mapping HTTP input to integration input
- Integrations (e.g. Lambda functions)
- Mapping integration output to HTTP output
- Body Model
You can use CloudFormation to define a REST API.
- Models: Define the input/output of the data
- Resources and Methods: e.g.
GET /userto retrieve a list of all users
- Endpoint: e.g.
You will now learn how to describe those components in CloudFormation. Remember that a CloudFormation template has the following structure:
Everything that you will learn now happens inside the
Resources block. The first resource is a REST API container to group all the following stuff.
Models are defined with JSON Schema. The ToDo applications stores users with three required fields:
uid: User id
Mapped to a model in CloudFormation, this looks like that:
You can also reference a model in a model for example if you want to define a list of users:
Now we need to define HTTP resources and methods.
We want our API to expose the list of all users under
GET /user. In CloudFormation we need to define the HTTP resource
/user and the HTTP Method
GET. We also define two optional query parameters
next to provide a paging interface.
I left the
Integration block empty to show you this important aspect now in more detail. The
Integration block defines the Lambda function invoked when an HTTP request arrives.
Now it’s time to describe the endpoint that we need to use the REST API.
It’s important that you explicitly depend on all the
Have a look at the following example to see the API in action.
clone the repository
create the lambda code file (
create an S3 bucket in the US East (N. Virginia,
us-east-1) region and upload the
lambda.zip file (replace
$S3Bucket with a S3 bucket name)
create cloudformation stack
wait until the stack is created (
$ApiGatewayEndpoint environment variable (replace
create a user
create a task
mark task as complete
create a task with a category
list tasks by category
delete CloudFormation stack
delete S3 bucket (replace
With API Gateway you can configure a RESTful API. You used a Lambda function to implement the functionality: Each HTTP request invokes a Lambda function. You have very limited overhead to operate your API because you only need to configure your API and implement the functionality. You don’t need to care about servers, scaling, and all the operational overhead.
To automate the configuration of API Gateway you used CloudFormation.