Boilerplate for Serverless APIs

A quick way to get started building a serverless API.

Tech stack

• Serverless framework
• AWS API Gateway HTTP APIs
• JWT authorizer using AWS Cognito
• AWS DynamoDB database
• Jest for testing
• Github Actions for CI/CD

Getting started

1. Name your service

Rename package name and service names:

• serverless.yml line 1
• package.json line 2

2. Dependencies

Install dependencies:

yarn

3. Custom domain (optional)

Uncomment the serverless-domain-manager plugin line and custom.customDomain lines in serverless.yml, and set the correct custom.baseDomain to set up a custom domain for your API.

---

Running locally

Start serverless-offline:

yarn start

This will start a local HTTP server on localhost:3000.

Authentication

When using yarn start, we're using serverless-offline with the --noAuth flag, which means that API endpoints that have an Authorizer set up will not check the JWT token in the Authorization header to authorize users as usual.

Instead, it will read from the file tests/local-auth.txt to simulate an authentication context. This will simulate a user with user ID c2dddd0e-fcb1-47ea-b232-cd24d05d8442.

Database access

There are packages available to set up DynamoDB testing environments locally (see serverless-dynalite for example).

What often seems easier, however, is to run a separate DynamoDB table in the cloud to test with during development. This provides an environment that is the closest to production.

That's also the default mode for this service:

• When you run yarn start, serverless-offline is started, using the serverless stage 'local' by default. That means that it will attempt to connect to a DDB table called {service}-local for any database interactions (this happens by setting the TABLE_NAME env var in serverless.yml).
• That does mean that you need AWS access. The AWS SDK will automatically try to use the credentials set up via the AWS CLI (and stored in ~/.aws/credentails).

A few tips:

• Default stage is local for both the yarn start and yarn deploy commands. You can supply a --stage parameter to customize this (other values we use: staging, production).
• Like everywhere with the AWS CLI, if you have multiple AWS profiles, you can use the env var AWS_PROFILE to set the credentials set to be used: AWS_PROFILE=myprofile yarn start

Invoke serverless function locally

To run a serverless function locally you can run the command serverless invoke local -f users-get -p data.json where data.json is the file containing the data for that request.

You can also use serverless invoke local -f users-get --data '{ "pathParameters":{"userId":"my-user-id"} }' to pass the data inline.

Have a look at the blog post "Local development with Serverless" for more information.

Testing

We use Jest to do simple unit tests per function.

Writing a test involves creating a file named test.js, calling the app function in your handler, and seeing if the output and called features is what we expect given a certain input object.

You can run the tests using yarn test.

Deployment

You can deploy manually using the yarn deploy command. By default, this will deploy to the local stage, but it is possible to override this to manually deploy to production:

yarn deploy --stage production

---

Get professional support for this package →
_{Custom consulting sessions availabe for implementation support and feature development.}