bottle-rest documentation

Welcome in the bottle-rest documentation. This package is used to make easier creating REST applications using Bottle web framework.

API documentation

What is it

bottle-rest is a collection of decorators, which can transform incoming data to parameters of your bottle functions/methods and outgoing data to JSON.

REST in bottle

Usually, when you try to write simple JSON REST API in bottle, you have to work with request object, read the request.body file, decode the JSON, do something with the decoded structure and return back some JSON encoded data.

This is not bad when you have to do it once, but can get pretty annoying when yout try to build something bigger and have to repeat the steps again and again.

bottle-rest

bottle-rest gives you three wrappers to make this repetitive work little bit easier: json_to_params(), json_to_data() and form_to_params().

All three of them maps input data to parameters of your function, so instead of code like*:

import json
from bottle import post, request, HTTPError

@post("/somepath")
def handler():
    if "somevar" not in body.json:
        raise HTTPError(400, "'somevar' parameter is required!")

    return json.dumps(
        database[body.json[somevar]]
    )

you can use just:

from bottle import post
from bottle_rest import json_to_params

@post("/somepath")
@json_to_params
def handler(somevar):
    return database[somevar]

*Edit: Returned dicts are by Bottle automatically converted to JSON, but other types are not. Thats why I am using explicit conversion (also, there is pretty print).

json_to_params

As you can probably guess from the name and see in the example, json_to_params() simply maps the incoming data to parameters for your function.

There are three possible things you can get from incoming JSON:

  • dictionary
  • list
  • basic type

Dictionary is mapped to kwargs of your functions, in non-rewrite mode (no existing kwargs key will be rewritten).

List and basic types are added at the end of the *args parameter of your function.

For the funtion in the example, you can send:

{
    "somevar": "somevalue"
}

or:

["somevalue"]

or:

"somevalue"

with same results.

All returned data from wrapped function will be automatically converted to the JSON, unless the return_json=False parameter is specified.

json_to_data

json_to_params() works almost identically as previous function, except that it puts all the decoded data into data parameter of your function, so better make sure, that you have it defined.

This can be useful for bigger sets of the data, which could be impractical to put into parameters.

All returned data from wrapped function will be automatically converted to the JSON, unless the return_json=False parameter is specified.

form_to_params

Finally form_to_params() works same way as json_to_params(), but it doesn’t decodes the input data, but data sent as GET or POST request parameters.

Note: In PHP, you would get this using the infamous $_GET and $_POST variables.

All returned data from wrapped function will be automatically converted to the JSON, unless the return_json=False parameter is specified.

Installation

Module is hosted at PYPI, and can be easily installed using PIP:

sudo pip install bottle-rest

Testing

This project uses pytest for testing. You can run the tests from the root of the package using following command:

$ py.test unittests/

Which will output something like:

============================= test session starts ==============================
platform linux2 -- Python 2.7.6 -- py-1.4.23 -- pytest-2.6.0
collected 13 items

unittests/test_bottle_rest.py .............

========================== 13 passed in 0.09 seconds ===========================

Source code

This project is released as opensource (MIT) and source codes can be found at GitHub:

Indices and tables