simple-spaceapi/README.md

Simple SpaceAPI

A lightweight SpaceAPI server with both web and REST interfaces.

Built with Node.js and Strapi.

Quick Start

Install dependencies and start the server in development mode:

npm install
npm run develop

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

Usage

Just fill in the data according to the Schema Documentation. Version 15 is implemented.

All endpoint data can be added or modified via the admin panel or through the REST API.

To list all available API endpoints, use the Strapi CLI:

npm run strapi routes:list

API Tokens

To update data using requests, you need an API token.

Tokens can be generated and managed in the admin panel under Settings → API Tokens. You can also define token-specific permissions there.

For more details, see the Strapi API Tokens Documentation.

Examples

Some example requests using the HTTPie CLI:

Get the Main SpaceAPI Endpoint Info

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

Update the Hackspace State

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

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

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.

Units

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

• Humidity Sensor: use percent 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.

state.open Field

While the SpaceAPI specification defines state.open as a boolean (true or false), Simple SpaceAPI expects string values: "true", "false", or "undefined".

Boolean values (true, false) are technically accepted and will be parsed correctly, but this behavior is not recommended.

Deployment

Environment Variables

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

Start by copying the example file and editing it:

cp ./.env.example ./.env

Running with Docker Compose

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

docker compose up --build

By default, the server will be available at http://0.0.0.0:1337/.
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.

npm install --omit=dev
npm run build

It is recommended to run the server using PM2:

npm install pm2@latest --global
pm2 start npm -- start

Alternatively, the application can be started directly with:

npm 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
• Dynamic Map

Strapi

• Strapi Documentation
• Strapi CLI Reference