Skip to main content

pico framework for aws lambda with optional json schema validation

Project description

# lambdarest

[![Build Status](http://travis-ci.org/trustpilot/python-lambdarest.svg?branch=master)](https://travis-ci.org/trustpilot/python-lambdarest) [![Latest Version](https://img.shields.io/pypi/v/lambdarest.svg)](https://pypi.python.org/pypi/lambdarest) [![Python Support](https://img.shields.io/pypi/pyversions/lambdarest.svg)](https://pypi.python.org/pypi/lambdarest)

Python routing mini-framework for [AWS Lambda](https://aws.amazon.com/lambda/) with optional JSON-schema validation.

### Features

* `lambda_handler` function constructor with built-in dispatcher
* Decorator to register functions to handle HTTP methods
* Optional JSON-schema input validation using same decorator

## Installation

Install the package from [PyPI](http://pypi.python.org/pypi/) using [pip](https://pip.pypa.io/):

```bash
pip install lambdarest
```

## Getting Started

This module helps you to handle different HTTP methods in your AWS Lambda.

```python
from lambdarest import lambda_handler

@lambda_handler.handle("get")
def my_own_get(event):
return {"this": "will be json dumped"}


##### TEST #####


input_event = {
"body": '{}',
"httpMethod": "GET",
"path": "/"
}
result = lambda_handler(event=input_event)
assert result == {"body": '{"this": "will be json dumped"}', "statusCode": 200, "headers":{}}
```

## Advanced Usage

Optionally you can validate an incoming JSON body against a JSON schema:

```python
from lambdarest import lambda_handler

my_schema = {
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"body":{
"type": "object",
"properties": {
"foo": {
"type": "string"
}
}
}
}
}

@lambda_handler.handle("get", schema=my_schema)
def my_own_get(event):
return {"this": "will be json dumped"}


##### TEST #####


valid_input_event = {
"body": '{"foo":"bar"}',
"httpMethod": "GET",
"path": "/"
}
result = lambda_handler(event=valid_input_event)
assert result == {"body": '{"this": "will be json dumped"}', "statusCode": 200, "headers":{}}


invalid_input_event = {
"body": '{"foo":666}',
"httpMethod": "GET",
"path": "/"
}
result = lambda_handler(event=invalid_input_event)
assert result == {"body": '"Validation Error"', "statusCode": 400, "headers":{}}
```

### Query Params

Query params are also analyzed and validatable with JSON schemas.
Query arrays are expected to be comma separated, all numbers are converted to floats.

```python
from lambdarest import lambda_handler

my_schema = {
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"query":{
"type": "object",
"properties": {
"foo": {
"type": "array",
"items": {
"type": "number"
}
}
}
}
}
}

@lambda_handler.handle("get", schema=my_schema)
def my_own_get(event):
return event["json"]["query"]


##### TEST #####


valid_input_event = {
"queryStringParameters": {
"foo": "1, 2.2, 3"
},
"httpMethod": "GET",
"path": "/"
}
result = lambda_handler(event=valid_input_event)
assert result == {"body": '{"foo": [1.0, 2.2, 3.0]}', "statusCode": 200, "headers":{}}
```

### Routing

You can also specify which path to react on for individual handlers using the `path` param:

```python
from lambdarest import lambda_handler

@lambda_handler.handle("get", path="/foo/bar/baz")
def my_own_get(event):
return {"this": "will be json dumped"}


##### TEST #####


input_event = {
"body": '{}',
"httpMethod": "GET",
"path": "/foo/bar/baz"
}
result = lambda_handler(event=input_event)
assert result == {"body": '{"this": "will be json dumped"}', "statusCode": 200, "headers":{}}
```

## Anormal unittest behaviour with `lambda_handler` singleton

Because of python unittests leaky test-cases it seems like you shall beware of [this issue](https://github.com/trustpilot/python-lambdarest/issues/16) when using the singleton `lambda_handler` in a multiple test-case scenario.

## Tests

You can use pytest to run tests against your current Python version. To run tests for all platforms, use tox or the built-in `test-all` Make target:

```
make test-all
```

See [`setup.py`](setup.py) for test dependencies.


Release History
---------------

1.0.1 (2017-02-24)
+++++++++++++++++++

**This is not a backwards compatible change.**

First OSS release

**features**
- dispatching handler for individual HTTP methods
- (optional) jsonschema validation for endpoints
- automatic wrapping of responses

2.0.0 (2017-03-04)
+++++++++++++++++++

**This is not a backwards compatible change.**

**features**
- now json is divided into ["json"]["body"] for post body and ["json"]["query"] for json loaded query params
- jsonschema validation gets whole ["json"] object so remember to change your schemas/code!!!

2.1.0 (2017-03-06)
+++++++++++++++++++

**bugfixes**
- empty body and queryStringParameters are tolerated

**features**
- query parameters arrays are now supported
- array items are tried casted to numbers, defaulted to strings (see last README example)
- more tests

2.2.1 (2017-10-03)
+++++++++++++++++++

**features**
- builds and deploys automatically using travis to pypi and github releases

Project details


Release history Release notifications

This version
History Node

2.2.6

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
peachai-lambdarest-2.2.6.tar.gz (7.7 kB) Copy SHA256 hash SHA256 Source None Dec 11, 2017

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page