Readme.md 3.33 KB
Newer Older
Julian's avatar
Julian committed
1
# Hapi - The Hasi SpaceAPI Server
Julian's avatar
Julian committed
2 3 4 5 6 7
This server provides a [SpaceAPI 0.13](https://spaceapi.io) compatible API. And a status page.


## Features

* An API which lets you delete or replace every part of the SpaceAPI JSON document
8
* A status website with the following awesome features:
Julian's avatar
Julian committed
9 10 11
    * Javascript Optional
    * Automatic updates through Server Sent Events
    * Dynamic Favicon depending on space state
12
    * Configuration using the SpaceAPI
Julian's avatar
Julian committed
13
* A CSS file which you can use to show the current space status on your website
Julian's avatar
Julian committed
14 15 16
* Zero dependencies!


Julian's avatar
Julian committed
17 18 19 20
## Running the server 

Please set the following environment variables

Julian's avatar
Julian committed
21 22 23 24 25
| Name          | Description                                                                            | Default        |
|---------------|----------------------------------------------------------------------------------------|----------------|
| SPACE_PORT    | The port the server should listen on.                                                  | 3000           |
| SPACE_INIT    | Path to the initial JSON data. Needs to adhere to the [schema](./spaceApiSchema.json). | ./initial.json |
| SPACE_API_KEY | The API key which is needed for updating the space status.                             | secret         |
Julian's avatar
Julian committed
26

Julian's avatar
Julian committed
27 28
Then run `npm run start` or just `node index.js`. Be sure to set the working path to the directory index.js resides in!
 
Julian's avatar
Julian committed
29
## Viewing the status
Julian's avatar
Julian committed
30 31
Execute a GET request at / to get the complete status as a JSON file.
Execute a GET request at / with `'accept': 'text/html'` to get an overview of the status as an HTML file.
Julian's avatar
Julian committed
32 33 34 35 36

## Updating the status
If you want to update things, your request needs an `authorization` header containing the API key specified in the 
`SPACE_API_KEY` variable.
Execute a PUT or POST request to any valid sub-path described in the [SpaceAPI 0.13 Docs](https://spaceapi.io/docs/) to 
Julian's avatar
Julian committed
37 38
update it. For example, to set the address of the space, execute a POST or PUT request to `/location/address` with an HTML
body containing the new address. You can also POST to non-leaf nodes by providing valid JSON in the request body. 
Julian's avatar
Julian committed
39 40 41 42 43 44 45 46 47 48 49 50
For example, you can POST (or PUT) the JSON object `{"m4": "http://hacker.space/stream.m4"}` to `/stream/`. 
This does work for every path besides `/`. If you want to update or create a new entry in an array, please use indexes. 
For example: `/sensors/temperature/0/value` with an HTTP body of `5`.

The response body of each valid update contains the complete space status.

## Deleting parts of the status
If you want to delete things, your request needs an `authorization` header containing the API key specified in the 
`SPACE_API_KEY` variable.
You can execute an HTTP DELETE at any path besides `/` to delete the specified node and all its children.
The response body of each valid deletion contains the complete space status.

51
## Hiding Sensors on the Status Page
Julian's avatar
Julian committed
52
Sensors can be hidden on the status page by giving them the additional attribute: `"ext_hide_on_page": true`. 
53 54 55 56 57 58 59 60 61 62
Example:
```json
{
  "value": 20,
  "location": "main room",
  "unit": "°C",
  "ext_hide_on_page": true
}
```

Julian's avatar
Julian committed
63 64 65 66 67 68
## Using `status.css`
Hapi offers a CSS file which changes according to the status (open/closed) of your hackspace at `/status.css`. You
can set the content of `status.css` by POSTing CSS to `/ext_css_open` and `/ext_css_closed` respectively.
If there is no content for the current state, an empty CSS file is returned.


Julian's avatar
Julian committed
69