REST APIs have become a common way to establish an interface between web back-ends and front-ends, and between different web services. The simplicity of this kind of interface, and the ubiquitous support of the HTTP and HTTPS protocols across different networks and frameworks, makes it an easy choice when considering interoperability issues.

Bottle is a minimalist Python web framework. It is lightweight, fast, and easy to use, and is well-suited to building RESTful services. A bare-bones comparison made by Andriy Kornatskyy put it among the top three frameworks in terms of response time and throughput (requests per second). In my own tests on the virtual servers available from DigitalOcean, I found that the combination of the uWSGI server stack and Bottle could achieve as low as a 140μs overhead per request.

In this article, I’ll provide a walkthrough of how to build a RESTful API service using Bottle.

Bottle: A Fast and Lightweight Python Web Framework

Installation and Configuration

The Bottle framework achieves its impressive performance in part thanks to its light weight. In fact the entire library is distributed as a one-file module. This means that it does not hold your hand as much as other frameworks, but it is also more flexible and can be adapted to fit into many different tech stacks. Bottle is therefore best suited for projects where performance and customizability are at a premium, and where the time-saving advantages of more heavy-duty frameworks are less of a consideration.

The flexibility of Bottle makes an in-depth description of setting up the platform a bit futile, since it may not reflect your own stack. However, a quick overview of the options, and where to learn more about how to set them up, is appropriate here:

Installation

Installing Bottle is as easy as installing any other Python package. Your options are:

  • Install on your system using the system’s package manager. Debian Jessie (current stable) packages the version 0.12 as python-bottle.
  • Install on your system using the Python Package Index with pip install bottle.
  • Install on a virtual environment (recommended).

To install Bottle on a virtual environment, you’ll need the virtualenv and pip tools. To install them, please refer to the virtualenv and pip documentation, though you probably have them on your system already.

In Bash, create an environment with Python 3:

$ virtualenv -p `which python3` env

Suppressing the -p `which python3` parameter will lead to the installation of the default Python interpreter present on the system – usually Python 2.7. Python 2.7 is supported, but this tutorial assumes Python 3.4.

Now activate the environment and install Bottle:

$ . env/bin/activate
$ pip install bottle

That’s it. Bottle is installed and ready to use. If you’re not familiar with virtualenv or pip, their documentation is top notch. Take a look! They are well worth it.

Server

Bottle complies with Python’s standard Web Server Gateway Interface (WSGI), meaning it can be used with any WSGI-compliant server. This includes uWSGI, Tornado, Gunicorn, Apache, Amazon Beanstalk, Google App Engine, and others.

The correct way to set it up varies slightly with each environment. Bottle exposes an object that conforms to the WSGI interface, and the server must be configured to interact with this object.

To learn more about how to set up your server, refer to the server’s docs, and to Bottle’s docs, here.

Database

Bottle is database-agnostic and doesn’t care where the data is coming from. If you’d like to use a database in your app, the Python Package Index has several interesting options, like SQLAlchemy, PyMongo, MongoEngine, CouchDB and Boto for DynamoDB. You only need the appropriate adapter to get it working with the database of your choice.

Bottle Framework Basics

Now, let’s see how to make a basic app in Bottle. For code examples, I will assume Python >= 3.4. However, most of what I’ll write here will work on Python 2.7 as well.

A basic app in Bottle looks like this:

import bottle

app = application = bottle.default_app()

if __name__ == '__main__':
    bottle.run(host = '127.0.0.1', port = 8000)

When I say basic, I mean this program doesn’t even “Hello World” you. (When was the last time you accessed a REST interface that answered “Hello World?”) All HTTP requests to 127.0.0.1:8000 will recieve a 404 Not Found response status.

Apps in Bottle

Bottle may have several instances of apps created, but for the sake of convenience the first instance is created for you; that’s the default app. Bottle keeps these instances in a stack internal to the module. Whenever you do something with Bottle (such as running the app or attaching a route) and don’t specify which app you’re talking about, it refers to the default app. In fact, the app = application = bottle.default_app() line doesn’t even need to exist in this basic app, but it is there so that we can easily invoke the default app with Gunicorn, uWSGI or some generic WSGI server.

The possibility of multiple apps may seem confusing at first, but they add flexibility to Bottle. For different modules of your application, you might create specialized Bottle apps by instantiating other Bottle classes and setting them up with different configurations as needed. These different apps could be accessed by different URLs, through Bottle’s URL router. We won’t delve into that in this tutorial, but you are encouraged to take a took at Bottle’s documentation here and here.

Server Invocation

The last line of the script runs Bottle using the indicated server. If no server is indicated, as is the case here, the default server is Python’s built-in WSGI reference server, which is only suitable for development purposes. A different server can be used like this:

bottle.run(server='gunicorn', host = '127.0.0.1', port = 8000)

This is syntactic sugar that let’s you start the app by running this script. For example, if this file is named main.py, you can simply run python main.py to start the app. Bottle carries quite an extensive list of server adapters that can be used this way.

Some WSGI servers don’t have Bottle adapters. These can be started with the server’s own run commands. On uWSGI, for instance, all you’d have to do would be to call uwsgi like this:

$ uwsgi --http :8000 --wsgi-file main.py

A Note on File Structure

Bottle leaves your app’s file structure entirely up to you. I’ve found my file structure policies evolve from project to project, but tend to be based on an MVC philosophy.

Building Your REST API

Of course, nobody needs a server that only returns 404 for every requested URI. I’ve promised you we’d build a REST API, so let’s do it.

Suppose you’d like to build an interface that manipulates a set of names. In a real app you would probably use a database for this, but for this example we will just use the in-memory set data structure.

The skeleton of our API might look like this. You can place this code anywhere in the project, but my recommendation would be a separate API file, such as api/names.py.

from bottle import request, response
from bottle import post, get, put, delete

_names = set()                    # the set of names

@post('/names')
def creation_handler():
    '''Handles name creation'''
    pass

@get('/names')
def listing_handler():
    '''Handles name listing'''
    pass

@put('/names/<name>')
def update_handler(name):
    '''Handles name updates'''
    pass

@delete('/names/<name>')
def delete_handler(name):
    '''Handles name deletions'''
    pass

Routing

As we can see, routing in Bottle is done using decorators. The imported decorators post, get, put, and delete register handlers for these four actions. Understanding how these work can be broken down as follows:

  • All of the above decorators are a shortcut to the default_app routing decorators. For example, the @get() decorator applies bottle.default_app().get() to the handler.
  • The routing methods on default_app are all shortcuts for route(). So default_app().get('/') is equivalent to default_app().route(method='GET', '/').

So @get('/') is the same as @route(method='GET', '/'), which is the same as @bottle.default_app().route(method='GET', '/'), and these can be used interchangeably.

One helpful thing about the @route decorator is that if you’d like, for example, to use the same handler to deal with both object updates and deletes, you could just pass a list of methods it handles like this:

@route('/names/<name>', method=['PUT', 'DELETE'])
def update_delete_handler(name):
    '''Handles name updates and deletions'''
    pass

Alright then, let’s implement some of these handlers.

Concoct your perfect REST API with Bottle Framework.

RESTful APIs are a staple of modern web development. Serve your API clients a potent concoction with a Bottle back-end.

POST: Resource Creation

Our POST handler might look like this:

import re, json

namepattern = re.compile(r'^[a-zA-Z\d]{1,64}$')

@post('/names')
def creation_handler():
    '''Handles name creation'''

    try:
        # parse input data
        try:
            data = request.json()
        except:
            raise ValueError

        if data is None:
            raise ValueError

        # extract and validate name
        try:
            if namepattern.match(data['name']) is None:
                raise ValueError
            name = data['name']
        except (TypeError, KeyError):
            raise ValueError

        # check for existence
        if name in _names:
            raise KeyError

    except ValueError:
        # if bad request data, return 400 Bad Request
        response.status = 400
        return
    
    except KeyError:
        # if name already exists, return 409 Conflict
        response.status = 409
        return

    # add name
    _names.add(name)
    
    # return 200 Success
    response.headers['Content-Type'] = 'application/json'
    return json.dumps({'name': name})

Well, that’s quite a lot. Let’s review these steps part by part.

Body Parsing

This API requires the user to POST a JSON string at the body with an attribute named “name”.

The request object imported earlier from bottle always points to the current request and holds all of the request’s data. Its body attribute contains a byte stream of the request body, which can be accessed by any function that is able to read a stream object (like reading a file).

The request.json() method checks the headers of the request for the “application/json” content type and parses the body if it’s correct. If Bottle detects a malformed body (e.g.: empty or with wrong content type), this method returns None and thus we raise a ValueError. If malformed JSON content is detected by the JSON parser; it raises an exception that we catch and reraise, again as a ValueError.

Object Parsing and Validation

If there are no errors, we have converted the request’s body into a Python object referenced by the data variable. If we’ve received a dictionary with a “name” key, we’ll be able to access it via data['name']. If we received a dictionary without this key, trying to access it will lead us to a KeyError exception. If we’ve received anything other than a dictionary, we’ll get a TypeError exception. If any of these errors occur, once again, we reraise it as a ValueError, indicating a bad input.

To check if the name key has the right format, we should test it against a regex mask, such as the namepattern mask we created here. If the key name isn’t a string, namepattern.match() will raise a TypeError, and if it doesn’t match it will return None.

With the mask in this example, a name must be an ASCII alphanumeric with no blanks from 1 to 64 characters. This is a simple validation and it doesn’t test for an object with garbage data, for example. More complex and complete validation may be achieved through the use of tools such as FormEncode.

Testing for Existence

The last test before fulfilling the request is whether the given name already exists in the set. In a more structured app, that test should probably be done by a dedicated module and signaled to our API through a specialized exception, but since we’re manipulating a set directly, we have to do it here.

We signal the existence of the name by raising a KeyError.

Error Responses

Just as the request object holds all the request data, the response object does the same for the response data. There are two ways of setting the response status:

response.status = 400

and:

response.status = '400 Bad Request'

For our example, we opted for the simpler form, but the second form may be used to specify the error’s text description. Internally, Bottle will split the second string and set the numeric code appropriately.

Success Response

If all the steps are successful, we fulfill the request by adding the name to the set _names, setting the Content-Type response header, and returning the response. Any string returned by the function will be treated as the response body of a 200 Success response, so we simply generate one with json.dumps.

GET: Resource Listing

Moving on from name creation, we’ll implement the name listing handler:

@get('/names')
def listing_handler():
    '''Handles name listing'''

    response.headers['Content-Type'] = 'application/json'
    response.headers['Cache-Control'] = 'no-cache'
    return json.dumps({'names': list(_names)})

Listing the names was much easier, wasn’t it? Compared to name creation there isn’t much to do here. Simply set some response headers and return a JSON representation of all names, and we’re done.

PUT: Resource Update

Now, lets see how to implement the update method. It’s not very different from the create method, but we use this example to introduce URI parameters.

@put('/names/<oldname>')
def update_handler(name):
    '''Handles name updates'''

    try:
        # parse input data
        try:
            data = json.load(utf8reader(request.body))
        except:
            raise ValueError

        # extract and validate new name
        try:
            if namepattern.match(data['name']) is None:
                raise ValueError
            newname = data['name']
        except (TypeError, KeyError):
            raise ValueError

        # check if updated name exists
        if oldname not in _names:
            raise KeyError(404)

        # check if new name exists
        if name in _names:
            raise KeyError(409)

    except ValueError:
        response.status = 400
        return
    except KeyError as e:
        response.status = e.args[0]
        return

    # add new name and remove old name
    _names.remove(oldname)
    _names.add(newname)

    # return 200 Success
    response.headers['Content-Type'] = 'application/json'
    return json.dumps({'name': newname})

The body schema for the update action is the same as for the creation action, but now we also have a new oldname parameter in the URI, as defined by the route @put('/names/<oldname>').

URI Parameters

As you can see, Bottle’s notation for URI parameters is very straightforward. You can build URIs with as many parameters as you’d like. Bottle automatically extracts them from the URI and passes them to the request handler:

@get('/<param1>/<param2>')
def handler(param1, param2):
    pass

Using cascading route decorators, you may build URIs with optional parameters:

@get('/<param1>')
@get('/<param1>/<param2>')
def handler(param1, param2 = None)
    pass

Also, Bottle allows for the following routing filters in URIs:

  • int

Matches only parameters that may be converted to int, and passes the converted value to the handler:

@get('/<param:int>')
def handler(param):
    pass
  • float

The same as int, but with floating point values:

@get('/<param:float>')
def handler(param):
    pass
  • re (regular expressions)

Matches only parameters which match the given regular expression:

@get('/<param:re:^[a-z]+$>')
def handler(param):
    pass
  • path

Matches subsegments of the URI path in a flexible way:

@get('/<param:path>/id>')
def handler(param):
    pass

Matches:

  • /x/id, passing x as param.
  • /x/y/id, passing x/y as param.

DELETE: Resource Deletion

Like the GET method, the DELETE method brings us little news. Just note that returning None without setting a status returns a response with an empty body and a 200 status code.

@delete('/names/<name>')
def delete_handler(name):
    '''Handles name updates'''

    try:
        # Check if name exists
        if name not in _names:
            raise KeyError
    except KeyError:
        response.status = 404
        return

    # Remove name
    _names.remove(name)
    return

Final Step: Activating the API

Supposing we’ve saved our names API as api/names.py , we can now enable these routes in the main application file main.py.

import bottle
from api import names

app = application = bottle.default_app()

if __name__ == '__main__':
    bottle.run(host = '127.0.0.1', port = 8000)

Notice we’ve only imported the names module. Since we’ve decorated all the methods with their URIs attached to the default app, there is no need to do any further setup. Our methods are already in place, ready to be accessed.

Nothing makes a front-end happy like a well-made REST API. Works like a charm!

Bonus: Cross Origin Resource Sharing (CORS)

One common reason to build a REST API is to communicate with a JavaScript front-end through AJAX. For some applications, these requests should be allowed to come from any domain, not just your API’s home domain. By default, most browsers disallow this behavior, so let me show you how to set up cross-origin resource sharing (CORS) in Bottle to allow this:

from bottle import hook, route, response

_allow_origin = '*'
_allow_methods = 'PUT, GET, POST, DELETE, OPTIONS'
_allow_headers = 'Authorization, Origin, Accept, Content-Type, X-Requested-With'

@hook('after_request')
def enable_cors():
    '''Add headers to enable CORS'''

    response.headers['Access-Control-Allow-Origin'] = _allow_origin
    response.headers['Access-Control-Allow-Methods'] = _allow_methods
    response.headers['Access-Control-Allow-Headers'] = _allow_headers

@route('/', method = 'OPTIONS')
@route('/<path:path>', method = 'OPTIONS')
def options_handler(path = None):
    return

The hook decorator allows us to call a function before or after each request. In our case, to enable CORS we must set the Access-Control-Allow-Origin, -Allow-Methods and -Allow-Headers headers for each of our responses. These indicate to the requester that we will serve the indicated requests.

Also, the client may make an OPTIONS HTTP request to the server to see if it may really make requests with other methods. With this sample catch-all example, we respond to all OPTIONS requests with a 200 status code and empty body.

To enable this, just save it and import it from the main module.

Wrap Up

That’s all there is to it!

With this tutorial, I’ve tried to cover the basic steps to create a REST API for a Python app with the Bottle web framework.

You can deepen your knowledge about this small but powerful framework by visiting its tutorial and API reference docs.

About the author

Leandro Lima, Brazil
member since August 17, 2015
Leandro has 12 years of experience with IT and has been working with Python since 2013. Graduated from university with a degree in Electrical Engineering, he has excellent analytical skills and a passion for building efficient and cost-effective systems. [click to continue...]
Hiring? Meet the Top 10 Freelance Bottle Developers for Hire in December 2016

Comments

Majid Lotfi
very nice tutorial, thanks lot.
Khaled Monsoor
nice & simple tutorial. Thanks. just a thing. As you have chosen Python3, possibly you have missed '()' around multiple exceptions. like in: except (TypeError, KeyError):
Lucas Le
Good content and details tutorial, but I don't see you mentioned about security/ web security
Leandro Lima
Lucas, I've tried to focus on giving a quickstart into Bottle's interface, dodging some subjects for the sake of conciseness. What security topics do you think that should have been covered?
Leandro Lima
Fixed. Thanks again Khaled!
Lucas Le
It might nice to have security topics about: + API Key + Integrate OAuth 2 MAC + Identifiers should be opaque + Query injection protection + Storage: data encryption
Leandro Lima
Yeah, I believe these topics are certainly pertinent to the general topic of building an API, but not to this article, as its goal was to talk about Bottle integration. I think that some of the topics you've suggested even make good topics for entire articles just about them. I'll keep a note of the list as a suggestion for future articles. Thanks :)
Rodion Promyshlennikov
Hi, Leandro! Thank you for this post. Probably we have a typo here: "data = request.json() except: raise ValueError" and we should use this instead: "data = request.json() except ValueError: raise" or "data = request.json() except Exception: raise ValueError"
Leandro Lima
Rodion, thanks for your message! I didn't understand your suggestion. My intention was to raise ValueError as a consequence of any exception raised by request.json(), like this: >>> try: ... raise KeyError('test') ... except: ... raise ValueError('new exception') ... Traceback (most recent call last): (...) >>>
Rodion Promyshlennikov
"except:" catches all exception in Python: KeyBoardInterrupt, SystemExit. Is it what you need? You should use "except Exception:" in case when you don't know which exception would be thrown, but it is very broad catch too.
Leandro Lima
Rodion, I haven't given much thought to which exceptions could be raised by the json parser and opted to catching all the exceptions. I agree with you that this can be improved by imposing better restrictions on the types of exceptions. I'll take a look at the docs and sleep on it. Thanks.
Mike Korshunov
Hello, thanks for great article! Do you know, if any tools available for testing our bottle API?
Vivek Deveshwar
data = request.json() never worked for me... it's not a method but a property, as per documentation below: --------------- http://bottlepy.org/docs/dev/api.html#bottle.BaseRequest.json json[source] If the Content-Type header is application/json or application/json-rpc, this property holds the parsed content of the request body. Only requests smaller than MEMFILE_MAX are processed to avoid memory exhaustion. Invalid JSON raises a 400 error response. --------------- So instead of request.json(), this is what worked for me: data = request.json
Leandro Lima
You're absolutely correct. This was indeed a lapse of mine.
James Parsons
Do you beleive that a framewrok as simple as Bottle still has relevence against more advanced Python frmaeworks such as Django or Flask?
Leandro Lima
I've been working with Flask a lot, recently. I think that comparing Bottle and Django unfair to both of them -- it's apples and oranges. But with Flask, that's indeed a fair question. Flask's learning curve and boilerplate code is sufficiently low that maybe anything you'd do with Bottle can also be done with Flask just as quickly. I think I'd still use Bottle for microservices, though. I see Bottle in a position that is an intermediate between Flask and Werkzeug.
comments powered by Disqus
Subscribe
The #1 Blog for Engineers
Get the latest content first.
No spam. Just great engineering and design posts.
The #1 Blog for Engineers
Get the latest content first.
Thank you for subscribing!
You can edit your subscription preferences here.
Trending articles
Relevant technologies
About the author
Leandro Lima
Python Developer
Leandro has 12 years of experience with IT and has been working with Python since 2013. Graduated from university with a degree in Electrical Engineering, he has excellent analytical skills and a passion for building efficient and cost-effective systems.