SpaceAPI Server

A lightweight server for SpaceAPI endpoints. Includes support for pluggable templating, so dynamic content, like sensor values, can be added.

Dependencies

Python 3 (>=3.6)
Bottle
Jinja2

License

MIT License

Usage

python -m spaceapi_server config.json

Configuration

{
    "address": "::1",     # The address to listen on.
    "port": 8000,         # The TCP port to listen on.
    "server": "wsgiref",  # The Bottle backend server to use.
    "template": "template.json",  # Path to the SpaceAPI response template file.
    "plugins_dir": "plugins",     # Path to the directory containing your plugins.

    "plugins": {
        # Plugin-specific configuration should go in here, e.g. `.plugins.sqlite.database`
    }
}

Serve a Static SpaceAPI Endpoint

Have a look at SpaceAPI: Getting Started. If you only want to serve static content, your template.json may consist of regular JSON data, which is served almost-as-is (once parsed and re-serialized).

Add Dynamic Content

This example guides you through adding a dynamic .state property to your SpaceAPI endpoint. We'll use the following (rather simple, and probably not too useful) data source: Check a certain file, and mark the space as open depending on its existence.

Create a plugin to fetch the data. Let's name it mybackend.py and put in in our plugins directory:

import os
from spaceapi_server import config, plugins

@plugins.template_function
def space_state():
    # Get the plugin config dict
    conf = config.get_plugin_config('mybackend')
    # Get the filename
    filename = conf.get('filename', '/var/space_state')
    try:
        # Get the file's properties
        stat = os.stat(filename)
    except FileNotFoundError:
        # File doesn't exist, aka. space is closed
        return {
            'open': False
        }
    # File exists, aka. space is open.  Also report the mtime as "last changed" timestamp
    return {
        'open': True,
        'lastchange': int(stat.st_mtime)
    }

The @template_function decorator registers the function as a callable in Jinja's globals. There's also @template_filter, which registers a Jinja2 filter, and @template_test, which registers a test. For more information on the Jinja2 templating engine, see Jinja2.

Call the template function in your template:
```
{
    # ...
    "state": "{{ space_state() }}"
    # ...
}
```
Although the value for the state key is a string containing the Jinja2 template, the return value of your template function is a complex data type, which will be inserted into the result as such. Please be aware that only the first token of a templated string is used in the result. This limitation is caused by the way Jinja2 is (ab-) used.

Configure the server:

# ...
"template": "template.json",
"plugins_dir": "plugins",
"plugins": {
    "mybackend": {
        "filename", "/var/space_state"
    }
}
# ...

Start the server and query it.

3.8 KiB Raw Blame History