aws-lambda-proxy-router

A hapi inspired router for AWS Lambda proxy functions

The purpose of this package is to easily organize the mapping between your code and your API request within Lambda functions that have more than one purpose. This takes away the need for the configuration of mapping templates and handles the standard event object that Amazon sends through with Lambda functions with proxy configuration. The desired effect of the package is to make it easier to build microservices that have multiple API Gateway endpoints.

As this package relates to linking API Gateway and Lambda together, the request IDs for both services are logged out to CloudWatch so when an error occurs in API Gateway, you can search the for the Gateway request ID to find the logs. More information on this can be found here.

Contents

• Usage
• Defining Routes
• Handler Function
• Request Object
• Response Function
• Contributing

Usage

Add aws-lambda-proxy-router to your project

$ npm install --save alpr

If you're using yarn:

$ yarn add alpr

Lambda index handler:

import Alpr from 'alpr';

function handler(event, context, callback) {
  const alpr = new Alpr({ event, context, callback });

  alpr.route({
    method: 'GET',
    path: '/url/{variableName}',
    handler: (request, response) => {
      response({
        statusCode: 200,
        headers: {},
        body: { hello: "world" }
      });
    },
  });

  alpr.route({
    method: [
      'GET',
      'POST',
    ],
    path: [
      '/url/url-level-2/{variableName}',
      '/url/url-level-2/data/{variableName}',
    ],
    handler: (request, response) => {
      response({
        statusCode: 200,
        headers: {},
        body: { hello: "world" }
      });
    },
  });

  if (!alpr.routeMatched) {
    // request resource did not match a route
    callback({
      statusCode: 404,
      headers: {},
      body: { message: "Route not found" }
    });
  }
}

export { handler };

Setting up your endpoint in API Gateway

Create your endpoint in API Gateway for the Lambda function and check the Use Lambda Proxy integration box. Then point your endpoint to the lambda function that has that route specified.

Routes

Routes are used to match a request to a given handler and are easily defined by the route method on the instance of the router. The route method takes one object parameter which should contain 3 keys.

| Key | Type | Value |---|---|--- | method | string/Array | The http method the route should match for. More than one can be specified | path | string/Array | This should match the value of the route specified in API gateway including path parameter names | handler | Function | The handler function for the given route. Should take two parameters of request and response.

Before creating a route the router must be instanced. This is done like so:

const alpr = new Alpr(event, context, callback);

Creating an instance requires specifying all the Lambda parameters as parameters to the router.

An example of defining routes that match on single and multiple endpoints can be found in the usage section.

It is important to note that only one route can be matched per instance. In cases where the route and method is the same in multiple route definitions only the first route will call the handler, the second will be ignored.

Handler

The handler is the method that get called when a route matches. It accepts two parameters request and response.

Request

The request parameter is an object that contains details about the request, everything that is sent through the event and context parameters in the Lambda function is accessible through this object.

Here's all the keys that are currently available in the request object:

| Key | Type | Value |---|---|--- | request.contextObject | Object | The whole lambda context object. | request.eventObject | Object | The whole lambda event object. | request.stageVariables | Object | The API Gateway stage variables. | request.queryStringParameters | Object | Query string parameters. | request.body | Object | The JSON parsed body. | request.rawBody | string | The raw body input. | request.pathParameters | Object | Request path parameters. | request.headers | Object | Request headers. | request.allParams | Object | The pathParameters, queryStringParameters and body, merged into one object. Note if variables have identical names, queryStringParameters will overwrite pathParameters and pathParameters will overwrite body.

Response

The response parameter is used to send a response back to API gateway. This method requires a parameter object to specify the body, headers and http status code.

| Key | Type | Value | Default |---|---|---|--- | params | Object | Parameters object | {} | params.statusCode | integer | The HTTP status code | 200 | params.headers | Object | Any headers to be returned in the response. | {} | params.body | mixed | Your response body, whatever is specified will be JSON.stringify'd. If body is not set the body will be defined as the params object. | JSON.stringify(params) | params.isBase64Encoded | boolean | This is usually used for serving binary data from an API. | false

Here is the recommended way to call the response method.

response({
    statusCode: 200,
    headers: { "x-your-header": "header value" },
    body: { "response-object-key": "data" },
});

More information about the proxy response object can be found on the AWS documentation.

If any of the correct parameters are not specified, default values of empty headers, statusCode 200, and a stringified value of whatever was sent in the parameter for the body are used to make the response valid.

So response('hello world') would work out as:

{
    statusCode: 200,
    headers: {},
    body: "hello world"
}

The specific structure used here is what API Gateway requires to map the responses correctly.

Contributing

• Start a feature branched from master
• Tests should be written for any new features in the test directory.
• Code should follow the installed style guide of airbnb.
• Tests and linting can be run with npm test.
• Once your feature is complete submit a PR to the master branch.