Skip to content

Latest commit

 

History

History
125 lines (102 loc) · 5.42 KB

README.md

File metadata and controls

125 lines (102 loc) · 5.42 KB
Raw

Serverless Contract Management API - AWS Node.js Typescript

Nodejs workflow Coverage Status

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