handlerfunction: The handler using parsed parameters as the first argument
Note: The (slightly modified) original event and context can be accessed as additional handler parameters
Endpoint Options
limit: ...
deprecated: ...
versioning: ...
logSuccess: ...
logError: ...
allowUnknownJson (default false): Allow unknown json body parameters
Api Parameters
There are various pre-defined parameters available
Bool: Boolean input
IsoDate: Date input as YYYY-MM-DD
Email: Email input
Enum: Enum input
FieldsParam: String input that gets parsed as object-fields
GeoPoint: GPS coordinate input
GeoPoly: GPS coordinate of polygon input and holes
GeoPolyList: List of GPS coordinate of polygon input and holes
GeoRect: GPS coordinate rectangle input
GeoShape: GPS coordinate polygon input
GeoShapeList: GPS coordinate polygon list input
Int: Integer input
IntShort: Short Integer input
IsoTimestamp: Iso timestamp input
Json: Json input that has to conform to Joi schema
Json-list: List of Json input that has to conform to Joi schema
List: List input
NumberList: Number list input
NumberParam: Number input
Regex: String input that has to conform to a regex
Str: String input
StrList: String list input
UUID: Uuid input
Parameter Types
There are four types of parameter types:
json: parsed from the json request body
query: parsed from the query string
header: parsed from the header and case insensitive
context: parsed from the lambda event context. Useful to e.g. obtain the client IP
Parameter Options
Below are the default parameter options. Most parameters have several customization options. Please see implementation for details.
required
Allow input to be not present
Type: boolean
Default: true
nullable
Allow input value to be null. Note: Parameter position must be in [json, context]
Type: boolean
Default: false
getter
Experimental
Note: only recommended for advanced use cases.
Optionally asynchronous custom "getting" of variables.
Getter function takes raw input from event, IE a query parameter will always pass String values into the getter function.
Warnings:
If used with { nullable: true }, if a rawInput is passed as null, or if a non-required parameter is not sent, the getter function will not be used.
Some params (such as Bool, Int, Json, etc) do extra processing after the getter function has returned, and may return inconsistent results. Thorough testing is recommended.
Takes unresolved parameters as second parameter. Simple parameters can be accessed directly, unresolved can be resolved by using await.
Parameter names are converted to camel case when passed into the handler.
E.g. the header X-Custom-Header would be passed as xCustomHeader.
Api Response
There are two types of api responses: Success and error responses. Error responses need to be thrown, while success responses
need to be returned from the endpoint handler. The following responses are available:
Success: ApiResponse (e.g. for plain text), JsonResponse (for json), BinaryResponse (e.g. for images)
Failure: ApiError
Success responses take the positional parameters data (required), statusCode (optional) and headers (optional).
Error responses take the positional parameters message (required), statusCode (optional), messageId (optional) and context (optional). They are always of Json format. It is recommended that an easily identifiable messageId is set on all error responses.
Please see implementation for details.
Rate Limiting
Done globally through the API configuration. However can be overwritten on a per-endpoint basis
by specifying limit as an integer in the endpoint definition option.
Rate limiting uses memory by default, which is not shared across function containers. However one can configure S3 to share the rate limiting (recommended). This will (1) increase latency and (2) increase costs per api call.
By default the client IP (['requestContext.identity.sourceIp']) is used for rate limiting. However this can be customized.
General Notes
Each endpoint definition can also be exposed as a separate lambda function. However this is not recommended for
larger APIs due to CloudFormation limitations (maximum number of resources and stack invalidation issues).
Consider using yaml-boost for loading Serverless Framework configuration.
Consider using a single router function instead of declaring each function individually.
Swagger Documentation
To generate swagger documentation we can call api.generateSwagger() after the api is initialized with routes. For merge-overwrite the swagger definition fs.smartWrite() can be used.