# Simple SpaceAPI

A lightweight [SpaceAPI](https://spaceapi.io/) server
with both web and REST interfaces.

Built with Node.js and [Strapi](https://github.com/strapi/strapi).

![Screenshot](/docs/images/screenshot-main.png?raw=true)

## Quick Start

Install dependencies and start the server in development mode:

```sh
npm install
npm run develop
```

Most files are autogenerated.<br>
The main entry point is `./src/api/spaceapi/controllers/spaceapi.ts`.

## Usage

All endpoint data can be added or modified
via the [admin panel](http://localhost:1337/admin)
or through the REST API.

To list all available API endpoints,
use the [Strapi CLI](https://docs.strapi.io/cms/cli):

```sh
npm run strapi routes:list
```

### API Tokens

To update data, you need an API token.<br>
Tokens can be generated and managed in the admin panel, under
[Settings → API Tokens](http://localhost:1337/admin/settings/api-tokens).<br>
You can also define token-specific permissions there.

For more details, see the
[Strapi API Tokens Documentation](https://docs.strapi.io/cms/features/api-tokens).

### Examples

Some example requests using the [HTTPie CLI](https://httpie.io/cli):

#### Get the Main SpaceAPI Endpoint Info

```sh
http GET http://localhost:1337/api/spaceapi
```

#### Update the Hackspace State

```sh
API_TOKEN=your-token-here

http PUT \
  http://localhost:1337/api/state \
  Authorization:"Bearer $API_TOKEN" \
  data:='{
    "open": true,
    "trigger_person": "Owner",
    "message": "We are open!"
  }'
```

#### Update a Sensor

```sh
API_TOKEN=your-token-here

# Discover the `documentId` for the Sensor
http GET \
  http://localhost:1337/api/temperature-sensors \
  Authorization:"Bearer $API_TOKEN"

DOCUMENT_ID=nrfn2800pexpwxuhqikzr7xa

http PUT \
  http://localhost:1337/api/temperature-sensors/$DOCUMENT_ID \
  Authorization:"Bearer $API_TOKEN" \
  data:='{
    "unit": "°C",
    "value": 25
  }'
```

#### Add an Event

```sh
API_TOKEN=your-token-here

http POST \
  http://localhost:1337/api/events \
  Authorization:"Bearer $API_TOKEN" \
  data:='{
    "name": "3D printer",
    "type": "finish-print",
    "extra": "Model: Evangelion Unit-01"
  }'
```

### Caveats

#### Timestamps

Simple SpaceAPI does not attempt to be smart about timestamps,
so **any** successful request will update the corresponding `lastchange` field.

For example, if you set the hackspace state to "closed"
and repeat the **same request** the next day,
the `lastchange` field will be updated.

#### Validation

While Simple SpaceAPI performs basic data validation,
it's still possible to produce invalid SpaceAPI JSON.

Always validate your endpoint using the
[SpaceAPI Validator](https://spaceapi.io/validator/).

#### Units

Due to some Strapi limitations,
certain sensor units must be replaced with aliases in API requests:

- Humidity Sensor: use `percents` instead of `%`
- Wind Sensor: use `degree` instead of `°`

The main SpaceAPI endpoint will display the correct units.

#### Sensor Structure

While Simple SpaceAPI follows the general SpaceAPI format,
the internal structure of some sensors is simplified:

- Radiation sensors (`alpha`, `beta`, `gamma`, `beta_gamma`)
  are unified into a single `radiation` type.
  The exact subtype can be specified using the `type` field.

## Deployment

### Environment Variables

Before running the production server,
you need to configure environment variables.

Start by copying the example file and editing it:

```sh
cp ./.env.example ./.env
```

### Running with Docker Compose

Once the environment variables are set up,
you can start the server using Docker Compose:

```sh
docker compose up --build
```

By default, the server will be available at `http://0.0.0.0:1337/`.<br>
The database and uploaded user files are stored in the `./data` directory.

You can change this behavior by editing the `.env` file
or the `docker-compose.yml` file, if needed.

**Note**: Environment variables defined in `docker-compose.yml`
will **override** those in the `.env` file.

### Running with Node.js

If you prefer to run the server without Docker, you can use Node.js directly.

```sh
npm install --omit=dev
npm run build
npm run start
```

By default, the server will be available at `http://0.0.0.0:1337/`.

You can change this behavior by editing the `.env` file, if needed.

## Resources

### SpaceAPI

- [SpaceAPI Schema Documentation](https://spaceapi.io/docs/)
- [Dynamic Map](https://mapall.space/)

### Strapi

- [Strapi Documentation](https://docs.strapi.io)
- [Strapi CLI Reference](https://docs.strapi.io/dev-docs/cli)