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

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, 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
  }'

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 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:

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 docker-compose.yml 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
npm run start

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

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

Resources

SpaceAPI

• SpaceAPI Schema Documentation
• Dynamic Map

Strapi

• Strapi Documentation
• Strapi CLI Reference