@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)

Validation with @OpenApi

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

Options

• swaggerDocPath: 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.

Security with @SecuredApi

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

• HTTP header 'x-authorization' must contain valid JWT token
• if configured, other validation must pass

Options

• header: if token is in 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.

API Response and Status handling with @StatusLogger

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.

Common errors:

• 'createInternalException': Argument is string (witch is logged). Returned is response with status code 500 with message "Internal Server Error. Use when some unexpected error happen (cannot connect to DB, etc. ...) - When is not required to let caller of API know what is wrong. But logs contains what is wrong.

Common logging with AWSLambdaLogger

Logger.

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