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-layercreate new lambda layer in AWS.
env/local.ymlincrease 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
- 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.
- '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 testto run test
npm run coverageto run test with coverage
npm run lintto 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:
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.