Update README.md

README.md

@@ -6,25 +6,134 @@ A simple [SpaceAPI](https://spaceapi.io/) endpoint with web and REST interfaces.
 
 Built with Node.js using [Strapi](https://github.com/strapi/strapi).
 
-## Deploy
+## Quick Start
 
-## Usage
+Install dependencies and start in development mode (with auto-reload):
 
-## Development
+```sh
-
+npm install
-Start the application with automatic reload:
-```
-npm i
 npm run develop
 ```
 
-## SpaceAPI Links
+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 endpoints.
+
+You could use the [Strapi CLI](https://docs.strapi.io/cms/cli)
+to list all availible 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 explanation see
+[Strapi Tokens Documentation](https://docs.strapi.io/cms/features/api-tokens).
+
+### Examples
+
+Some [HTTPIe CLI](https://httpie.io/cli) requests here:
+
+#### Get SpaceAPI 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 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
+
+#### Lastchange
+
+Simple SpaceAPI not trying to be smart about timespamps
+so **any** successful update will affect this 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`.
+  Type of the 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 Links
 
-- [Strapi GitHub repository](https://github.com/strapi/strapi)
+- [Strapi Documentation](https://docs.strapi.io)
-- [Strapi documentation](https://docs.strapi.io)
 - [STrapi Command Line Interface](https://docs.strapi.io/dev-docs/cli)