A lightweight SpaceAPI (spaceapi.io) endpoint server
Find a file
s3lph 8f21eb95e6
Some checks failed
ci/woodpecker/push/woodpecker Pipeline was successful
ci/woodpecker/tag/woodpecker Pipeline failed
chore: version 0.5.2
2023-10-25 04:13:17 +02:00
examples Update examples to v0.4 2021-12-07 03:42:04 +01:00
package chore: migrate from gitlab-ci to woodpecker 2023-10-25 04:10:48 +02:00
spaceapi_server Release v0.5.1 2023-10-05 02:01:40 +02:00
.gitignore Initial commit 2019-11-25 02:48:12 +01:00
.woodpecker.yml chore: migrate from gitlab-ci to woodpecker 2023-10-25 04:10:48 +02:00
CHANGELOG.md chore: version 0.5.2 2023-10-25 04:13:17 +02:00
LICENSE Add MIT License 2019-11-25 02:53:18 +01:00
README.md fix: various smaller issues in README 2023-10-05 00:10:10 +02:00
requirements.txt Initial commit 2019-11-25 02:48:12 +01:00
setup.cfg Initial commit 2019-11-25 02:48:12 +01:00
setup.py chore: migrate from gitlab-ci to woodpecker 2023-10-25 04:10:48 +02:00

SpaceAPI Server

pipeline status coverage report

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

Dependencies

License

MIT License

Introduction

This project is an attempt to implement a lightweight, yet versatile SpaceAPI endpoint server. In its simplest configuration, it just serves a plain, static, boring JSON document.

In order to provide dynamic content (e.g. whether your space is currently open), you can replace parts of the YAML document (anything except object keys) with custom plugin invocations. These plugins look up and return your dynamic content.

Input Output
---
api: "0.13"
api_compatibility: ["14"]
space: My Hackerspace
# This is a plugin invocation
# with no arguments
state: !space_state {}
sensors:
  # This is a plugin invocation with
  # arguments.  They are passed to the
  # plugin function as kwargs.
  network_connections: !network_connections
    networks: [ "2.4 GHz", "5 GHz" ]
{
  "api": "0.13",
  "api_compatibility": ["14"],
  "space": "My Hackerspace",
  "state": {
    "open": true,
    "lastchange": 1575160777,
    "message": "Visitors Welcome!"
  },
  "sensors": {
    "network_connections": [
      {
        "value": 4,
        "type": "wifi",
        "name": "2.4 GHz"
      },
      {
        "value": 7,
        "type": "wifi",
        "name": "5 GHz"
      }
    ]
  }
}

Usage

0. Download

Head over to the Releases, download and install the package that suits your needs. Alternatively, clone the repo and get started. There also is a Container Image available through the Gitlab registry tagged as registry.gitlab.com/s3lph/spaceapi-server.

The remainder of this document assumes that you installed the server as an OS distribution package.

1. Overview

The configuration of this server consists of three parts:

  • The main configuration file, usually located at /etc/spaceapi-server/config.yaml. This file controls all the internal settings of the server.
  • The response template file, located at /etc/spaceapi-server/template.yaml. This file defines the content served by your sever.
  • The plugins directory, located at /etc/spaceapi-server/plugins/. Here you can put your plugins for rendering dynamic content.

2. Configure the Server

Open the file /etc/spaceapi-server/config.yaml.

The following options are currently available:

---
# The address to listen on.
address: "::1"
# The TCP port to listen on.
port: 8000
# The Bottle backend server to use.
server: wsgiref
# Path to the SpaceAPI response template file.
template: template.yaml
# Path to the directory containing your plugins.
plugins_dir: plugins
plugins:
  # Plugin-specific configuration should go in here, separated by plugin
  my_plugin:
    my_option: "Hello, World!"
    my_other_option: [ 42, 1337 ]

3. Configure a Static SpaceAPI Endpoint

Open the file /etc/spaceapi-server/template.yaml. By default it contains a minimal example response. If you only want to serve static content, your template.json should simply contain the SpaceAPI JSON response you want to serve.

The content is served "almost-as-is" (apart from the conversion from YAML to JSON).

To learn about how a SpaceAPI response should look like, have a look at the SpaceAPI Website.

4. 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.

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

    import os
    from spaceapi_server import config, plugins
    
    @plugins.template_function
    # The plugin can be invoked by using the !space_state YAML tag
    def space_state():
        # Get the plugin config dict
        conf = config.get_plugin_config('filestate')
        # 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 a constructor in PyYAML's parser with the function's name as tag (e.g. `!space_state).

  2. Call the template function in your template:

    # ...
    state: !space_state
    # ...
    
  3. Configure the server:

    # ...
    template: template.yaml
    plugins_dir: plugins
    plugins:
      filestate:
        filename: /var/space_state
    # ...
    

5. Start the Server

Start the server with e.g.:

systemctl start spaceapi-server.service

To reload the configuration, template and plugins, send a SIGHUP, e.g. through systemctl reload.

If you need to run the server ad-hoc, you can start it with:

python3 -m spaceapi_server /path/to/config.yaml

6. Test the Server

curl http://localhost:8000/

You should be greeted with the SpaceAPI endpoint response.

Plugin API Reference

Configuration

The following functions provide access to values defined in the configuration file.

spaceapi_server.config.get_plugin_config(name: str)

This function returns a plugin's configuration.

The function takes one argument, the name of the plugin. This name is used to look up the plugin configuration.

The function returns the content present at the key .plugins.<name> of the global configuration file, or an empty object if absent.

Usage:

from spaceapi_server import plugins

print(plugins.get_plugin_config('my_plugin'))

Templating

The following decorators register a function for use as a PyYAML constructor, so they become usable from within templates. They are invoked when the template is rendered, which happens for each HTTP request.

If performance is an issue, consider applying caching, either in your plugins, or by using a caching HTTP reverse proxy.

spaceapi_server.plugins.template_function

This decorator registers the function's name as a YAML tag in the parser.

The decorated function may take arguments (always passed as **kwargs, so *args, or arguments before * won't work) that can be represented in a YAML file.

The decorated function may return any value that can be serialized into JSON. This includes objects and arrays.

Usage:

from spaceapi_server import plugins

@plugins.template_function
def lookup_sensor(query, default=None):
    # Do something with the query
    result = ...
    # If the lookup failed, return a default value
    if not result:
        return default or []
    return result
# ...
state: !lookup_sensor
  query: SELECT timestamp, value FROM people_now_present LIMIT 1
# ...