mirror of
https://github.com/He4eT/simple-spaceapi.git
synced 2026-05-04 17:37:24 +00:00
208 lines
4.8 KiB
Markdown
208 lines
4.8 KiB
Markdown
# 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).
|
|
|
|
|
|
|
|
## 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 using requests, 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.
|
|
|
|
#### `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:
|
|
|
|
```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)
|