lambda-proxy

A zero-requirement proxy linking AWS API Gateway {proxy+} requests and AWS Lambda.

Install

$ pip install -U pip
$ pip install lambda-proxy

Or install from source:

$ git clone https://github.com/vincentsarag/lambda-proxy.git
$ cd lambda-proxy
$ pip install -U pip
$ pip install -e .

Usage

With GET request

from lambda_proxy.proxy import API

APP = API(name="app")

@APP.route('/test/tests/<id>', methods=['GET'], cors=True)
def print_id(id):
    return ('OK', 'plain/text', id)

With POST request

from lambda_proxy.proxy import API

APP = API(name="app")

@APP.route('/test/tests/<id>', methods=['POST'], cors=True)
def print_id(id, body):
    return ('OK', 'plain/text', id)

Routes

Route schema is simmilar to the one used in Flask

Variable parts in the route can be specified with angular brackets /user/<username>. By default a variable part in the URL accepts any string without a slash however a different converter can be specified as well by using <converter:name>.

Converters:

• int: integer
• string: string
• float: float number
• uuid: UUID

example:

• /app/<user>/<id> (user and id are variables)
• /app/<string:value>/<float:num> (value will be a string, while num will be a float)

Route Options

• path: the URL rule as string
• methods: list of HTTP methods allowed, default: ["GET"]
• cors: allow CORS, default: False
• token: set access_token validation
• payload_compression_method: Enable and select an output body compression
• binary_b64encode: base64 encode the output body (API Gateway)
• ttl: Cache Control setting (Time to Live)
• description: route description (for documentation)
• tag: list of tags (for documentation)

Cache Control

Add a Cache Control header with a Time to Live (TTL) in seconds.

from lambda_proxy.proxy import API
APP = API(app_name="app")

@APP.route('/test/tests/<id>', methods=['GET'], cors=True, ttl=3600)
def print_id(id):
   return ('OK', 'plain/text', id)

Binary responses

When working with binary on API-Gateway we must return a base64 encoded string

from lambda_proxy.proxy import API

APP = API(name="app")

@APP.route('/test/tests/<filename>.jpg', methods=['GET'], cors=True, binary_b64encode=True)
def print_id(filename):
    with open(f"{filename}.jpg", "rb") as f:
        return ('OK', 'image/jpeg', f.read())

Enable compression (happens only if "Accept-Encoding" if found in headers)

from lambda_proxy.proxy import API

APP = API(name="app")

@APP.route('/test/tests/<filename>.jpg', methods=['GET'], cors=True, binary_b64encode=True, payload_compression_method="gzip")
def print_id(filename):
    with open(f"{filename}.jpg", "rb") as f:
       return ('OK', 'image/jpeg', f.read())

Simple Auth token

Lambda-proxy provide a simple token validation system.

• a "TOKEN" variable must be set in the environment
• each request must provide a "access_token" params (e.g curl http://myurl/test/tests/myid?access_token=blabla)

from lambda_proxy.proxy import API

APP = API(name="app")

@APP.route('/test/tests/<id>', methods=['GET'], cors=True, token=True)
def print_id(id):
    return ('OK', 'plain/text', id)

URL schema and request parameters

QueryString parameters are passed as function's options.

from lambda_proxy.proxy import API

APP = API(name="app")

@APP.route('/<id>', methods=['GET'], cors=True)
def print_id(id, name=None):
    return ('OK', 'plain/text', f"{id}{name}")

requests:

$ curl /000001
   0001

$ curl /000001?name=vincent
   0001vincent

Multiple Routes

from lambda_proxy.proxy import API
APP = API(name="app")

@APP.route('/<id>', methods=['GET'], cors=True)
@APP.route('/<id>/<int:number>', methods=['GET'], cors=True)
def print_id(id, number=None, name=None):
    return ('OK', 'plain/text', f"{id}-{name}-{number}")

requests:

$ curl /000001
   0001--

$ curl /000001?name=vincent
   0001-vincent-

$ curl /000001/1?name=vincent
   0001-vincent-1

Advanced features

Context and Event passing

Pass event and context to the handler function.

from lambda_proxy.proxy import API

APP = API(name="app")

@APP.route("/<id>", methods=["GET"], cors=True)
@APP.pass_event
@APP.pass_context
def print_id(ctx, evt, id):
    print(ctx)
    print(evt)
    return ('OK', 'plain/text', f"{id}")

Automatic OpenAPI documentation

By default the APP (lambda_proxy.proxy.API) is provided with three (3) routes:

• /openapi.json: print OpenAPI JSON definition

• /docs: swagger html UI

• /redoc: Redoc html UI

Function annotations

To be able to render full and precise API documentation, lambda_proxy uses python type hint and annotations link.

from lambda_proxy.proxy import API

APP = API(name="app")

@APP.route('/test/<int:id>', methods=['GET'], cors=True)
def print_id(id: int, num: float = 0.2) -> Tuple(str, str, str):
    return ('OK', 'plain/text', id)

In the example above, our route /test/<int:id> define an input id to be a INT, while we also add this hint to the function print_id we also specify the type (and default) of the num option.

Examples

• https://github.com/vincentsarago/lambda-proxy/tree/master/example
• https://github.com/RemotePixel/remotepixel-tiler

Contribution & Devellopement

Issues and pull requests are more than welcome.

Dev install & Pull-Request

$ git clone https://github.com/vincentsarago/lambda-proxy.git
$ cd lambda-proxy
$ pip install -e .[dev]

This repo is set to use pre-commit to run flake8, pydocstring and black ("uncompromising Python code formatter") when committing new code.

$ pre-commit install
$ git add .
$ git commit -m'my change'
   black.........................Passed
   Flake8........................Passed
   Verifying PEP257 Compliance...Passed
$ git push origin

License

See LICENSE.txt.

Authors

See AUTHORS.txt.

Changes

See CHANGES.txt.