From 5c6065996ef2f213d73193a2ddfaba99b6be4820 Mon Sep 17 00:00:00 2001 From: s3lph Date: Sat, 30 Nov 2019 03:24:29 +0100 Subject: [PATCH] More readme --- README.md | 128 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 102 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 6cca514..70d14f1 100644 --- a/README.md +++ b/README.md @@ -3,8 +3,9 @@ [![pipeline status](https://gitlab.com/s3lph/spaceapi-server/badges/master/pipeline.svg)][master] [![coverage report](https://gitlab.com/s3lph/spaceapi-server/badges/master/coverage.svg)][master] -A lightweight server for [SpaceAPI][spaceapi] endpoints. Includes support for pluggable templating, so dynamic content, -like sensor values, can be added. +A lightweight server for [SpaceAPI][spaceapi] endpoints. Includes +support for pluggable templating, so dynamic content, like sensor +values, can be added. ## Dependencies @@ -16,13 +17,47 @@ like sensor values, can be added. [MIT License][mit] +## 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 JSON document (anything +except object keys) with [Jinja2 templates][jinja], from which you can +invoke custom plugins, which look up and return your dynamic content. + ## Usage -```bash -python -m spaceapi_server config.json -``` +### 0. Download -## Configuration +Head over to the [Releases][releases], download and install the +package that suits your needs. Alternatively, clone the repo and get +started. + +The remainder of this document will assume 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.json`. This file controls all the + internal settings of the server. +- The **response template** file, located at + `/etc/spaceapi-server/template.json`. 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.json`. + +The following options are currently available: ```json { @@ -33,23 +68,36 @@ python -m spaceapi_server config.json "plugins_dir": "plugins", # Path to the directory containing your plugins. "plugins": { - # Plugin-specific configuration should go in here, e.g. `.plugins.sqlite.database` + # Plugin-specific configuration should go in here, separated by plugin + "my_plugin": { + "my_option": "Hello, World!", + "my_other_option: [ 42, 1337 ] + } } } ``` -## Serve a Static SpaceAPI Endpoint +### 3. Configure a Static SpaceAPI Endpoint -Have a look at [SpaceAPI: Getting Started][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). +Open the file `/etc/spaceapi-server/template.json`. 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. -## Add Dynamic Content +The content is served "almost-as-is" (once parsed and re-serialized). -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. +To learn about how a SpaceAPI response should look like, have a look +at [SpaceAPI: Getting Started][spaceapi-getting-started]. -1. Create a plugin to fetch the data. Let's name it `mybackend.py` and put in in our plugins directory: +### 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: ```python import os @@ -58,7 +106,7 @@ its existence. @plugins.template_function def space_state(): # Get the plugin config dict - conf = config.get_plugin_config('mybackend') + conf = config.get_plugin_config(filestate') # Get the filename filename = conf.get('filename', '/var/space_state') try: @@ -76,9 +124,11 @@ its existence. } ``` - 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][jinja]. + 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][jinja]. 2. Call the template function in your template: @@ -90,9 +140,12 @@ its existence. } ``` - 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. + 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. 3. Configure the server: @@ -101,19 +154,42 @@ its existence. "template": "template.json", "plugins_dir": "plugins", "plugins": { - "mybackend": { - "filename", "/var/space_state" + "filestate": { + "filename": "/var/space_state" } } # ... ``` -4. Start the server and query it. +### 5. Start the Server + +Start the server with e.g.: + +```bash +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: + +```bash +python3 -m spaceapi_server /path/to/config.json +``` +### 6. Test the Server + +```bash +curl http://localhost:8000/ +``` + +You should be greeted with the SpaceAPI endpoint response. [master]: https://gitlab.com/s3lph/spaceapi-server/commits/master +[releases]: https://gitlab.com/s3lph/spaceapi-server/-/releases [spaceapi]: https://spaceapi.io/ [pypi-bottle]: https://pypi.org/project/bottle/ [pypi-jinja2]: https://pypi.org/project/Jinja2/ [mit]: https://gitlab.com/s3lph/spaceapi-server/blob/master/LICENSE [spaceapi-getting-started]: https://spaceapi.io/getting-started/ -[jinja]: https://jinja.palletsprojects.com/ \ No newline at end of file +[jinja]: https://jinja.palletsprojects.com/