@besmarthead/sh-api-framework

What is SH API Framework

Annotations and libraries (utils) to help solve common tasks with API. Can be used as NPM package or as Lambda layer.

• validation (with swagger / openapi): annotation '@OpenApi'
• security (JWT validation): annotation '@SecuredApi'
• API status handler/logger (ERROR/OK): annotation '@StatusLogger'
• AWS Logger: util class 'AWSLambdaLogger'

Library as Lambda layer

• npm run lambda-layer create new lambda layer in AWS.
• in env/local.yml increase version of lambda layer
• commit/push (all other packages will after deploy use new lambda version)

QA

• npm run test to run test
• npm run coverage to run test with coverage
• npm run lint to run lint

How to release

Requirement: have user in NPM and be part of team: "developers" in organization "besmarthead" (https://www.npmjs.com/settings/besmarthead/teams/team/developers/users)

• Check if user is logged into NPM (npm whoami). If user is not logged: npm login
• lerna publish --no-private

All API projects/packages have in package.json set "private" to true. When publishing with lerna argument "--no-private", those packages are ignored" from publish. Doc: lerna#--no-private

@SecuredApi: Security

Lambda Security implementation (authentication & authorization)

If handler is annotated with @SecuredAPI than API caller must be valid user (e.g. valid token in request):

• authentication (is token valid / authentic)
• authorization (SH Admin required, specific role required)

Options

• header: if token is in a different header, set name of header here

• isSHAdmin: If set to REQUIRED, user must be SH admin. If set to ALLOW and user is SH admin than other validations are skipped.

@OpenApi: Validation

Lambda OpenApi validation (request/response validation)

Validation of request / response with Swagger.

• Required is to have valid swagger file on path /src/openapi-doc.yaml.
• If handler is annotated with @OpenApi than path of handler defined in serverles.yaml (to which is handler bind) must be also defined in swagger file.
• Request and response is validated

If lambda can be invoked (not as API through AWS Gateway), add configuration invokableLambda.

Options

• swaggerDocPath: a custom path to swagger file.
• apiPrefix: when try to find path of handler in swagger file -> this prefix is add. example: when run in AWS and API is deployed to custom domain, all API has prefix which is not part of path of handler.
• skipResponseValidator: should be validation of response skipped.
• invokableLambda: If lambda is invoked -> search in swagger file for resource by httpMethod and resource as defined in configuration

invokableLambda: {
  httpMethod: 'GET',
  resource: '/profile/{id}/activities'
}

(if lambda would be invoked without this configuration - swagger validation would fail, resouce would npt be found)

@StatusLogger: API Response and Status handling

AWS Lambda functions are monitored with Elastic (logstash, elasticsearch, kibana, ...). If handler is annotated by this method:

• and handler returns some entity (JSON object), logged is status "OK"
• and handler throw exceptions, logged is status "ERROR" and monitoring systems (like Kibana watcher) can raise alert.

AWSLambdaLogger: Common logging

Lambda Error handling And Exceptions

• use methods in src/types/exception.types.ts