mirror of
https://github.com/He4eT/simple-spaceapi.git
synced 2026-05-04 17:37:24 +00:00
139 lines
3.1 KiB
Markdown
139 lines
3.1 KiB
Markdown
# Simple SpaceAPI
|
|
|
|
A simple [SpaceAPI](https://spaceapi.io/) server with web and REST interfaces.
|
|
|
|
Built with Node.js using [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 the data for your endpoint could be added and modified
|
|
with the [admin panel](http://localhost:1337/admin)
|
|
or with the REST API.
|
|
|
|
You could use the [Strapi CLI](https://docs.strapi.io/cms/cli)
|
|
to list all availible API endpoints:
|
|
|
|
```sh
|
|
npm run strapi routes:list
|
|
```
|
|
|
|
### API Tokens
|
|
|
|
To update the data you need to obtain the API token.<br>
|
|
You could define token's specific permissions in the admin panel.
|
|
|
|
For additional details see
|
|
[Strapi Tokens Documentation](https://docs.strapi.io/cms/features/api-tokens).
|
|
|
|
### Examples
|
|
|
|
Some [HTTPIe CLI](https://httpie.io/cli) requests here:
|
|
|
|
#### Main SpaceAPI Endpoint
|
|
|
|
```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 the Sensors
|
|
|
|
```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
|
|
}'
|
|
```
|
|
|
|
### Caveats
|
|
|
|
#### Timestamps
|
|
|
|
Simple SpaceAPI not trying to be smart about timespamps
|
|
so **any** successful update will affect the corresponded `lastchange` field.
|
|
|
|
For example if you set the hackspace state to "closed"
|
|
and repeat the same request next day
|
|
then `lastchange` will be overrided.
|
|
|
|
#### Validation
|
|
|
|
While Simple SpaceAPI is trying to validate the data
|
|
it's still possible to generate invalid SpaceAPI JSON.
|
|
|
|
Do not forget to check your endpoint with the
|
|
[SpaceAPI Validator](https://spaceapi.io/validator/).
|
|
|
|
#### Units
|
|
|
|
Due to the some Strapi limitations
|
|
several sensor units should be replaced with aliases for API requests:
|
|
|
|
- Humidity Sensor: use `percents` instead of `%`;
|
|
- Wind Sensor: use `degree` instead of `°`;
|
|
|
|
Main SpaceAPI endpoint will show correct units.
|
|
|
|
#### Shape of Sensors
|
|
|
|
While Simple SpaceAPI is trying to follow the SpaceAPI structure,
|
|
some sensors shape is simplified:
|
|
|
|
- Nested `alpha`, `beta`, `gamma` and `beta_gamma` radiation sensors
|
|
were unified as generic `radiation` sensor.
|
|
Type of this sensor could be specified with `type` field.
|
|
|
|
## Deployment
|
|
|
|
TBD
|
|
|
|
## Resources
|
|
|
|
### SpaceAPI Links
|
|
|
|
- [SpaceAPI Schema Documentation](https://spaceapi.io/docs/)
|
|
- [Dynamic Map](https://mapall.space/)
|
|
|
|
### Strapi Links
|
|
|
|
- [Strapi Documentation](https://docs.strapi.io)
|
|
- [Strapi Command Line Interface](https://docs.strapi.io/dev-docs/cli)
|