spaceapid/README.md

# SpaceAPI Daemon

`spaceapid` serves a [SpaceAPI](https://spaceapi.io)-compatible JSON on port 8080:

```shell
$ curl http://localhost:8080 | jq
{
  "api_compatibility": [
    "14"
  ],
  "space": "CCCHH",
  ...
}
```

## Configuring

spaceapid has to be configured via one or multiple json files.
A sample configuration is provided as [config-template.json](./config-template.json).
The config consists of three parts:

- `"credentials"`
	- List of Username/Password credentials for HTTP BasicAuth
- `"dynamic"`
	- The configuration for the dynamic parts of the message
- `"response"`
	- The static (pre-filled) parts of the response

See [Running](#Running) for details.

## Building

See the `go.mod` file for minimum required Go version.
There are currently no dependencies apart from the Go standard library.

``` shell
go build -ldflags '-X main.version=v420.69-rc23' .
```

## Running

Set the environment variable to a comma-separated list of config files or pass the `-c` flag.

```shell
env CONFIG_PATH=config-template.json go run .
# OR
go run . -c config-credentials.json,config-dynamic.json,config-response.json
```

## Updating values

The state of the boolean `state->open` and `state->message` property can be modified via `/state/{open,message}`:

```shell
curl -X PUT -u user:password -d true http://localhost:8080/state/open
curl -X PUT -u user:password -d "Nur mit Passierschein A38 :3" http://localhost:8080/state/message
```

As `state->message` is optional, its value can be deleted by using the `PUT` method with an empty payload, or by using `DELETE`:

```shell
curl -X PUT -u user:password -d "" http://localhost:8080/state/message
# OR
curl -X DELETE -u user:password http://localhost:8080/state/message
```

The same updating procedure applies for the endpoints for sensors configured under `"dynamic"`.
Currently only the sensors with the `value/unit/location/name/description` schema are implemented.
At the time of writing this includes `temperature`, `barometer`, `humidity`, `beverage_supply`, `power_consumption`, and `account_balance`.
Out-of-spec sensors may be used as well, as long as they share the same schema.

```shell
curl -X PUT -u user:password -d 23.42 http://localhost:8080/sensors/{temperature,humidity,...}[/location[/name]]
```

As can be seen in the example, the http urls are generated from sensor type and optionally `location` and `name`.
Depending on sensor type, `location` might be required for your sensors, see the schema for details.