Create a serverless RESTful API with the Serverless Framework powered by API Gateway, Lambda, and DynamoDB

This article teaches you how to create a Serverless RESTful API on AWS with the Serverless Framework. 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 describing the API in CloudFormation read Create a serverless RESTful API with API Gateway, CloudFormation, Lambda, and DynamoDB instead!

Implementing a RESTful API with API Gateway, Lambda, and DynamoDB

API Gateway provides a HTTP API endpoint that is fully configurable. You define the HTTP resources (like /user), the HTTP methods on that resources (like POST, GET, 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.

Wiring together and deploying API Gateway and Lambda is time-consuming and error-prone. The Serverless Framework does all the heavy lifting for you. With just one command you get started.

The Serverless Framework

The Serverless Framework is under active development by Serverless, Inc., which was recently funded by the investors behind Docker, New Relic and Meteor.

To setup a new project you first need to install the Serverless Framework:

npm install -g serverless@1.0.0-rc.1

Now it’s time to create a new project folder:

mkdir my-first-service && cd my-first-service
serverless create --template aws-nodejs

As a user of the framework you will get in touch with a YAML configuration file called serverless.yml.

The first part of the configuration defines the runtime:

service: aws-nodejs
provider: aws
runtime: nodejs6.10

After that the interesting part starts: functions:

functions:
  getUsers:
    handler: handler.getUsers
    events:
    - http:
        path: user
        method: get

Let’s look at them line by line:

getUsers: Name of the function.
handler: handler.getUsers Maps to a JavaScript file handler.js exporting the function getUsers.
The magic happens inside the events: section where API Gateway is defined as an event source. HTTP GET requests on resource /user are mapped to the getUsers function.

The implementation of the function in handler.js is the same as with plain AWS Lambda.

module.exports.getUsers = (event, context, cb) => cb(null, {});

With one command you can deploy your service.

serverless deploy

This will package all the Source files, upload the zip file to S3 and create everything that is needed to do what you described in the configuration file. You can serverless deploy multiple times to update your service.

To remove the deployed service you run:

serverless remove

Have a look at the following example to see the Serverless Framework in action.

Example

The example in this article reuses the multi-user ToDo application from chapter 10 in Amanzon Web Services in Action. You can find the code for the original example in the book’s code repository.

Setting up

clone the repository

$ git clone git@github.com:AWSinAction/apigateway.git
$ cd apigateway/

install the Serverless Framework

$ npm install -g serverless@1.0.0-rc.1

switch to the serverless-framework folder and install the dependencies

$ cd serverless-framework/
$ npm install --production

deploy the API

$ serverless deploy
[...]
Service Information
[...]
endpoints:
  GET - https://$ApiId.execute-api.us-east-1.amazonaws.com/dev/category/{category}/task
  PUT - https://$ApiId.execute-api.us-east-1.amazonaws.com/dev/user/{userId}/task/{taskId}
  DELETE - https://$ApiId.execute-api.us-east-1.amazonaws.com/dev/user/{userId}/task/{taskId}
  GET - https://$ApiId.execute-api.us-east-1.amazonaws.com/dev/user/{userId}/task
  POST - https://$ApiId.execute-api.us-east-1.amazonaws.com/dev/user/{userId}/task
  GET - https://$ApiId.execute-api.us-east-1.amazonaws.com/dev/user/{userId}
  DELETE - https://$ApiId.execute-api.us-east-1.amazonaws.com/dev/user/{userId}
  GET - https://$ApiId.execute-api.us-east-1.amazonaws.com/dev/user
  POST - https://$ApiId.execute-api.us-east-1.amazonaws.com/dev/user
functions:
[...]

export the API endpoint from above in a environment variable to easily make calls the the API next.

export ApiGatewayEndpoint=" https://$ApiId.execute-api.us-east-1.amazonaws.com/dev"

Use the RESTful API

create a user

curl -vvv -X POST -d '{"email": "your@mail.com", "phone": "0123456789"}' -H "Content-Type: application/json" https://$ApiGatewayEndpoint/user

list users

curl -vvv -X GET https://$ApiGatewayEndpoint/user

create a task

curl -vvv -X POST -d '{"description": "test task"}' -H "Content-Type: application/json" https://$ApiGatewayEndpoint/user/$UserId/task

list tasks

curl -vvv -X GET https://$ApiGatewayEndpoint/user/$UserId/task

mark task as complete

curl -vvv -X PUT https://$ApiGatewayEndpoint/user/$UserId/task/$TaskId

delete task

curl -vvv -X DELETE https://$ApiGatewayEndpoint/user/$UserId/task/$TaskId

create a task with a category

curl -vvv -X POST -d '{"description": "test task", "category": "test"}' -H "Content-Type: application/json" https://$ApiGatewayEndpoint/user/$UserId/task

list tasks by category

curl -vvv -X GET https://$ApiGatewayEndpoint/category/$Category/task

Teardown

remove the API

$ serverless remove

Summary

The Serverless Framework makes deploying an serverless RESTful API very easy. 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.
The Serverless Framework also allows you to use SNS, SQS, S3, Scheduler, … as event sources.