More readme
This commit is contained in:
s3lph
parent
acb4dcad6e
commit
5c6065996e
1 changed files with 102 additions and 26 deletions
126
README.md
126
README.md
|
|
@ -3,8 +3,9 @@
|
|||
[][master]
|
||||
[][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,16 +154,39 @@ 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/
|
||||
|
|
|
|||
Loading…
Reference in a new issue