TypeScript icon, indicating that this package has built-in type declarations

1.0.21 • Public • Published

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


  • 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


  • 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



  • 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


DownloadsWeekly Downloads






Unpacked Size

77.6 kB

Total Files


Last publish


  • martin_smarthead