@besmarthead/sh-api-framework NPM

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.