A quick way to get started building a serverless API.

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

Rename package name and service names:

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

Install dependencies:

yarn

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.

Start serverless-offline:

yarn start

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

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.

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

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.

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.

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