Create a Serverless RESTful API With the Serverless Framework

DZone 's Guide to

Create a Serverless RESTful API With the Serverless Framework

Serverless architectures are what's hot. If you've ever considered diving in, then learn here how to do it powered by API Gateway, Lambda, and DynamoDB.

· Integration Zone ·
Free Resource

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

API Gateway flow from client request to Lambda and back

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. Only a few weeks are left when they’ll finally release v1 in fall 2016. You can get a preview at version 1 by using the beta release which is working fine.

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

npm install -g serverless@beta

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: nodejs4.3

After that, the interesting part starts: functions:

    handler: handler.getUsers
    - 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.


The example in this article reuses the multi-user ToDo application from chapter 10 in Amazon 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@beta

Switch to the serverless-framework folder and install the dependencies:

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

Deploy the API:

$ serverless deploy
Service Information
  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

Export the API endpoint from above in an environment variable to easily make calls to 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


Remove the API:

$ serverless remove

The Serverless Framework makes deploying a 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, etc. as event sources.

api ,endpoint ,lambda ,restful ,serverless

Published at DZone with permission of Michael Wittig . See the original article here.

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}