Workspaces API

Workspaces RESTful API.

Table of contents

• Endpoints
• Custom domain setup
• Development
• Monitoring
• CI/CD

Endpoints

TODO

Custom domain setup

The serverless domain manager plugin is used to configure the AWS API Gateway (APIG) domain.

Before deploying the first time, run:

sls create_domain

This only has to be done once to create the custom domain in APIG. After that, deploy the service, to create the proper base path mappings between the basePath and the service (i.e. API).

To remove the domain run:

sls delete_domain

Note that a DNS record has been created with the custom domain, which points to the APIG CloudFront distribution.

Development

Code linting and formatting

Code is automatically linted and formatted on commit, using ESLint and Prettier.

Available scripts

In the project directory, you can run:

npm test

Runs all (unit) tests.

npm run lint

Lints all code using ESLint.

npm run lint:format

Lints all code using ESLint, and formats it using Prettier.

npm run sls:debug

Prints the serverless.yaml configuration.

Monitoring

A Serverless dashboard has been setup for:

• Alerts (errors)
• RED metrics
• Basic observability based on:
  • Date & time
  • Function name
  • Execution duration
  • Memory usage
  • Cold start time
  • Errors

CI/CD

CircleCI is used to:

• Audit npm dependencies for security vulnerabilities.
• Run unit/integration tests (Jest).
• Deploy services via Serverless Framework.

Serverless Framework

CircleCI requires a "Serverless Personal Access Key" to deploy services. This is configured as an environment variable named SERVERLESS_ACCESS_KEY in the CircleCI credentials context. The value of the access key can be found in the 1Password "Upstand FM" vault under "Serverless access key for CircleCI".

The access key allows the Serverless CLI (used by CircleCI in the release job) to authenticate with the Serverless Framework Dashboard.
Additionally, an access role has been configured to help secure resource deployments on AWS, by enabling the Serverless Framework to issue temporary AWS access keys to deploy resources. These keys are generated by Serverless Framework on every command, and the credentials expire after one hour.

The Serverless Framework leverages AWS Security Token Service and the AssumeRole API to automate creating and usage of temporary credentials, so your developers can stay productive and work securely without doing this manually.

We also use a separate CloudFormation role to limit access during deployment, to only the required set of permissions needed by Serverless to deploy resources (i.e. no AdministratorAccess). This is done by setting provider.cfnRole in the Serverless manifest.