aws-wave
AWS Lambda Microframework
About AWS Wave
AWS Wave is a microframework that makes it easier to develop rest api's using AWS Lambda Functions and API Gateway. It attempts to make the develpment faster by easing common tasks, such as:
- Exception handling
- Request body deserialization
- Response body serialization
- Request validation
Lambda Proxy Integration
In order to use AWS Wave all methods defined in the API Gateway must use Request Integration Type:LAMBDA_PROXY
.
A detailed documentation can be found here.
Getting Started
Instalation
npm install aws-wave
Handling Requests
The AWS Wave microframework provides an abstract class called AbstratRequestHandler that handles a Lambda execution call and perform some operations such as request body deserialization, request validation, response body serialization and exception handling.
const AbstractRequestHandler = AbstractRequestHandler; { // perform anything before the execution this; } { ; } exports { const handler = ; handler;}
The Request / Response Attributes
The AbstractRequestHandler class provides methods to access all the request / response attributes and the Lambda environment context as well:
Attribute | Method |
---|---|
Request Headers | getRequestHeader("headerName") |
Response Headers | addResponseHeader("headerName") |
Raw Request Body | getRawRequestBody() |
Http Method | getHttpMethod() |
Resource Path | getPath() |
Stage Variables | getStageVariable("stageVariableName") |
Path Parameters | getPathParameter("parameterName") |
Query String Parameters | getQueryStringParameter("parameterName") |
Request Context Parameter | getRequestContextParameter("parameterName") |
Request Validation
AWS Wave uses Joi to validate requests. To validate the incoming request a schema should be defined in the class constructor
Eg.:
const Joi = ;const AbstractRequestHandler = AbstractRequestHandler; const schema = Joiobject; { superschema; } { this; } { ; } exports { const handler = ; handler;}
If any constraint violation occurs an UnprocessableEntityException will be thrown and the http response will be serialized with the error details.
Eg.:
curl -X POST http://my-api-gateway-resource/phone-confirmations -d '{"invalidParam": "value"}'
I this particular example the server will respond the above request with a http status code 422 and the following response body:
A detailed documentation of Joi validations can be found here.
If you want to provide your own request body validation mechanism, the method resolveRequestBodyValidator should be overridden:
const Wave = ; const RequestBodyValidator = WaveRequestBodyValidator;const UnprocessableEntityException = WaveUnprocessableEntityException; { // custom validation here // should throw a HttpException if any constraint is violated throw message: 'Invalid request body'; } moduleexports = MyCustomValidator;
const MyCustomValidator = ;const AbstractRequestHandler = AbstractRequestHandler; const myCustomSchema = {}; { supermyCustomSchema; } { this; } { ; } { return ; } exports { const handler = ; handler;}
Serialization and Deserialization
The current version of AWS Wave supports only JSON serialization/deserialization.
The deserialization and serialization strategies are based on two http headers:
- Content-Type for deserialization
- Accept for serialization
If you want to provide your own request body deserializer, the method resolveRequestBodyDeserializer should be overridden:
const Wave = ; const BadRequestException = WaveBadRequestException;const RequestBodyDeserializerStrategy = WaveRequestBodyDeserializerStrategy; { // custom deserialization here // should throw a HttpException if any error occur throw message: 'Invalid request body'; } moduleexports = MyCustomDeserializer;
If you want to provide your own response body serializer, the method resolveResponseBodySerializer should be overridden:
const Wave = ; const InternalServerErrorException = WaveInternalServerErrorException;const RequestBodyDeserializerStrategy = WaveResponseBodySerializerStrategy; { // custom serialization here // should throw a HttpException if any error occur throw message: 'Unable to serialize the response body'; } moduleexports = MyCustomSerializer;
Exception Handling
AWS Wave offers a built in exception handler, any HttpException will be serialized as response body and any exception not handled will be serialized as an Internal Server Error.
E.g.:
const Wave = ; const AbstractRequestHandler = WaveAbstractRequestHandler;const UnauthorizedException = WaveUnauthorizedException; { this; } { // any validation if bodyhasPermission return ; ; } exports { const handler = ; handler;}
License
The AWS Wave microframework is open-source software licensed under the MIT license .