API Gateway Response Builder

This module will help you build a valid API Gateway response from your lambda function.

Install

npm i @kdcio/api-gw-resp

Usage

import response from '@kdcio/api-gw-resp';

export const listMovies = (event) => {
  const body = {
    movies: [
      { name: 'Lord of the Rings' },
      { name: 'Forest Gump' },
      { name: 'Breaveheart' },
    ],
  };
  return response.OK({ body });
};

The function above will return

{
  "statusCode": 200,
  "isBase64Encoded": false,
  "headers": {
    "Access-Control-Allow-Origin": "*",
    "Access-Control-Allow-Credentials": true,
    "Access-Control-Allow-Headers": "*"
  },
  "body": "{\"movies\":[{\"name\":\"Lord of the Rings\"},{\"name\":\"Forest Gump\"},{\"name\":\"Breaveheart\"}]}"
}

API

Successful responses

| Method | Code | Description | | ---------- | ---- | --------------------------------------------------------------------------------------------------------------------------- | | OK | 200 | Request has succeeded and the message body contains the requested information. | | CREATED | 201 | Request has succeeded and a new resource has been created. The message body may contain information about the new resource. | | NO_CONTENT | 204 | Request has succeeded but there is no content to be returned. |

Options

| Option | Type | Required | Default | Description | | ------- | ---------------------- | ----------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | body | object, string or null | :ballot_box_with_check: | null | object will be converted into JSON string and will have a Content-Type of application/json in the header.string will have a Content-Type of text/plain in the header. | | cors | bool | :ballot_box_with_check: | true | If true, will add cors in header | | origin | string | :ballot_box_with_check: | * | Set specific origin | | headers | object | :ballot_box_with_check: | {} | Specify additional headers |

Examples:

response.OK({ body: { name: 'John Doe' } });
response.CREATED({ body: { id: 1 } });
response.NO_CONTENT();

Redirect responses

| Method | Code | Description | | -------- | ---------- | ----------------------------------------------------------------------------------------------- | | REDIRECT | 301 or 302 | The URI of the requested resource has moved. The new URI can be found in the Location header. |

Options

| Option | Type | Required | Default | Description | | --------- | ------ | ----------------------- | ------- | ----------------------------------------------------------- | | permanent | bool | :ballot_box_with_check: | none | If true, status code will be 301. Otherwise it will be 302. | | location | bool | :ballot_box_with_check: | none | The new url where the resource has been moved. | | headers | object | :ballot_box_with_check: | {} | Specify additional headers |

Examples:

response.REDIRECT({
  permanent: true,
  location: 'https://www.google.com',
});

Client Error responses

| Method | Code | Description | | ------------ | ---- | --------------------------------------------------------------------------------------------------------------------- | | BAD_REQUEST | 400 | The server could not understand the request due to invalid syntax or missing parameters. | | UNAUTHORIZED | 401 | The client must authenticate itself to get the requested response. | | FORBIDDEN | 403 | The client is not allowed to access the requested resource. Unlike 401, the client's identity is known to the server. | | NOT_FOUND | 404 | The server can not find the requested resource. | | CONFLICT | 409 | This response is sent when a request conflicts with the current state of the server. Usually duplicate of data. |

Options

| Option | Type | Required | Default | Description | | ------- | ------ | ----------------------- | ---------------- | ------------- | | error | string | :ballot_box_with_check: | Status code name | Error name | | message | string | :white_check_mark: | none | Error message |

Examples:

response.BAD_REQUEST({ message: 'Missing username' });
response.UNAUTHORIZED({
  message: 'You need to login to access this resource.',
});
response.FORBIDDEN({ message: 'You are not allowed to access this resource.' });
response.NOT_FOUND({ message: 'Resource not found.' });
response.CONFLICT({ message: 'Duplicate username.' });

Server Error responses

| Method | Code | Description | | ------------ | ---- | --------------------------------------------------------------------- | | SERVER_ERROR | 500 | The server has encountered a situation it doesn't know how to handle. |

Options

| Option | Type | Required | Default | Description | | ------- | ------ | ----------------------- | --------------------- | ------------- | | error | string | :ballot_box_with_check: | Internal Server Error | Error name | | message | string | :white_check_mark: | none | Error message |

Examples:

response.SERVER_ERROR({ message: 'Internal server error.' });

Auto Detect Error responses

| Method | Description | | ------ | -------------------------------------------------------------------- | | ERROR | This will auto detect which error code to send based on the message. |

Options

| Option | Type | Required | Default | Description | | ------- | ------ | ------------------ | ------- | ------------- | | message | string | :white_check_mark: | none | Error message |

Error Messages

| Error Response | Regex matcher | | -------------- | --------------------------- | | BAD_REQUEST | /missing\|invalid/i | | UNAUTHORIZED | /unauthorized/i | | FORBIDDEN | /forbidden\|not allowed/i | | NOT_FOUND | /not found/i | | CONFLICT | /conflict\|duplicate/i |

Examples:

try {
  throw new Error('Missing username');
} catch (e) {
  // This will return status code 400 (BAD_REQUEST)
  return response.ERROR({ message: e.message });
}

More Examples

import parser from '@kdcio/api-gw-resp';
import response from '@kdcio/api-gw-resp';
import db from './db';

export const movie = async (event) => {
  const request = parser(event);
  let body = null;

  if (event.method === 'GET') {
    try {
      const movies = db.listMovies();
      return response.OK({ body: { movies } });
    } catch (e) {
      return response.BAD_REQUEST({ message: e.message });
    }
  } else if (event.method === 'POST') {
    try {
      const id = await db.insertMove(request.body);
      return response.OK({ body: { id } });
    } catch (e) {
      return response.BAD_REQUEST({ message: e.message });
    }
  } else if (event.method === 'PUT') {
    try {
      await db.updateMove(request.body);
      return response.NO_CONTENT();
    } catch (e) {
      return response.CONFLICT({ message: e.message });
    }
  }

  return response.BAD_REQUEST({
    message: 'Invalid method',
  });
};

Using ERROR method:

import parser from '@kdcio/api-gw-resp';
import response from '@kdcio/api-gw-resp';
import db from './db';

export const movie = async (event) => {
  const request = parser(event);
  let body = null;

  try {
    if (event.method === 'GET') {
      const movies = db.listMovies();
      return response.OK({ body: { movies } });
    } else if (event.method === 'POST') {
      const id = await db.insertMove(request.body);
      return response.OK({ body: { id } });
    } else if (event.method === 'PUT') {
      await db.updateMove(request.body);
      return response.NO_CONTENT();
    } else {
      throw new Error('Invalid method');
    }
  } catch (e) {
    // Will determine the correct status code based on the error message
    return response.ERROR({ message: e.message });
  }
};

Star Me

If you find this project useful, please consider giving a star. I would really appreciate it.

You can also:

See also

@kdcio/api-gw-resp

License

MIT