Serverless Contract Management API - AWS Node.js Typescript

This project is a demo for simple serverless contract management API which revloves aroud two resources

 Contract {
  contractId: string,
  name: string,
  templateId: string,
  userId: string
}

 User {
  userId: string,
  username: string,
  password: string
}

Installation/deployment instructions

Depending on your preferred package manager, follow the instructions below to deploy your project.

Requirements:

NodeJS lts/fermium (v.14.15.0). If you're using nvm, run nvm use to ensure you're using the same Node version in local and in your lambda's runtime.

serverless installed globally by npm i -g serverless

Using NPM

• Run npm i to install the project dependencies
• Run sls dynamodb install to install dynamodb locally
• Run sls offline start to run the project locally
• Run sls deploy to deploy this stack to AWS

Testing

Unit Tests

• Run npm test to run unit tests

Testing Locally

note: there is insomnia collection that can be imported by insomnia REST client to test the API

This Project contains a single lambda function triggered by an HTTP request made on the provisioned API Gateway REST API /contracts and /auth routes. The request body must be provided as application/json. The body structure is tested by API Gateway against src/functions/{function}/schema.ts JSON-Schema definition: it must contain the requierd properties.

below I am going to describe a simple flow

• you can register a user by sending POST request to localhost:3000/dev/auth/register and a request body that must include username and password like {"username":"ahmed", "password":"password"} and you recieve the created user id that is a uuid as { "userId": "{uuid}" }
• you can login by sending POST request to localhost:3000/dev/auth/login body that must include username and password like {"username":"ahmed", "password":"password"} and you recieve a valid JWT token to use as bearer token to access the contract resource API like { "token": "{jwt}" }
• you can create a contract sending POST request with a valid bearer roken and a body that must include name and template id that is a uuid like { "name":"somename", "templateId":"{uuid}" } and you recieve the created contract id as { "contractId": "{uuid}" }

note: contractId is generated by the api and userId is deducted from the jwt

• you can get the contract details by sending a GET request with a valid bearer token to localhost:3000/dev/contracts/{contractId} and get response as { "contractId": "{uuid}", "name": "somenae", "templateId": "{uuid}", "userId": "{uuid}" }

• you can get all contracts ids by sending a GET request with a valid bearer token to localhost:3000/dev/contracts/ and get a response as { "contracts": [ { "contractId": "{uuid}" }, ... ] }

Project structure

The project code base is mainly located within the src folder. This folder is divided in:

• functions - containing code base and configuration for your lambda functions
• libs - containing shared code base between your lambdas

.
├── src
│   ├── functions               # Lambda configuration and source code folder
│   │   ├── auth
│   │   │   ├── handler.ts      # `auth` lambda source code
│   │   │   ├── index.ts        # `auth` lambda Serverless configuration
│   │   │   └── schema.ts       # `auth` lambda input event JSON-Schema
│   │   └── contract
│   │       ├── handler.ts      # `contract` lambda source code
│   │       ├── index.ts        # `contract` lambda Serverless configuration
│   │       └── schema.ts       # `contract` lambda input event JSON-Schema
│   │   
│   │
│   └── libs                    # Lambda shared code
│       └── apiGateway.ts       # API Gateway specific helpers
│       └── handlerResolver.ts  # Sharable library for resolving lambda handlers
│       └── lambda.ts           # Lambda middleware
│
├── package.json
├── serverless.ts               # Serverless service file
├── tsconfig.json               # Typescript compiler configuration
├── tsconfig.paths.json         # Typescript paths

3rd party libraries

• json-schema-to-ts - uses JSON-Schema definitions used by API Gateway for HTTP request validation to statically generate TypeScript types in your lambda's handler code base
• middy - middleware engine for Node.Js lambda. This project uses http-json-body-parser to convert API Gateway event.body property, originally passed as a stringified JSON, to its corresponding parsed object
• @serverless/typescript - provides up-to-date TypeScript definitions for your serverless.ts service file