Crate spaceapi_server[][src]

Expand description

This crate enables you to create your own SpaceAPI server endpoint using Rust. In the end you’ll get a single binary that you can run on your server.


On the build machine:

On the server:

  • Redis

The Redis instance will be used to store dynamic data like sensor values, as well as keys for dynamic data update authentication.

Getting Started

Create a new Rust project:

cargo new --bin mystatus

Add the spaceapi-server dependency to Cargo.toml:

spaceapi-server = "0.4"

Create a

use spaceapi_server::api::{Contact, Location, StatusBuilder};
use spaceapi_server::SpaceapiServerBuilder;

fn main() {
    // Create new minimal v14 Status instance
    let status = StatusBuilder::v14("coredump")
        .location(Location {
            address: Some("Spinnereistrasse 2, 8640 Rapperswil, Switzerland".into()),
            lat: 47.22936,
            lon: 8.82949,
        .contact(Contact {
            irc: Some("irc://".into()),
            twitter: Some("@coredump_ch".into()),
        .expect("Creating status failed");

    // Set up server
    let server = SpaceapiServerBuilder::new(status)

    // Serve!
    let _ = server.serve("");

Now you can build and run your binary with cargo run. Running this code starts a HTTP server instance on port 8000. You can also override the port by setting the PORT environment variable.

See the examples/ directory for some other examples.


Registering Sensors

This crate supports updating and retrieving dynamic sensor values (e.g. temperature or people present). For this, first register a sensor with a sensor template:

use spaceapi_server::SpaceapiServerBuilder;
use spaceapi_server::api::sensors::{PeopleNowPresentSensorTemplate, TemperatureSensorTemplate};

let server = SpaceapiServerBuilder::new(status)
    .add_sensor(PeopleNowPresentSensorTemplate {
        location: Some("Hackerspace".into()),
        name: None,
        description: None,
        names: None,
    }, "people_now_present".into())
    .add_sensor(TemperatureSensorTemplate {
        unit: "°C".into(),
        location: "Room 1".into(),
        name: None,
        description: None,
    }, "temp_room1".into())
    .add_sensor(TemperatureSensorTemplate {
        unit: "°C".into(),
        location: "Room 2".into(),
        name: None,
        description: None,
    }, "temp_room2".into())
.expect("Could not initialize server");

(You can find the full example at examples/

This will register three sensors: One “people now present” sensor and two “temperature” sensors.

Updating Sensors via HTTP

If you start the server like that, the JSON output will not yet contain any sensor data. To update a sensor value, send a HTTP POST request to the /sensors/<sensor-id>/ endpoint with the value parameter:

curl -v -X PUT -d value=42
curl -v -X PUT -d value=13.37

Now the server response will contain the following key:

"sensors": {
  "people_now_present": [
      "location": "Hackerspace",
      "value": 42
  "temperature": [
      "unit": "°C",
      "location": "Room 1",
      "value": 13.37

Updating Sensors via Redis

Alternatively you can modify the values in Redis directly. You can access the database with the redis-cli tool:

% redis-cli> SET people_now_present 1
OK> GET people_now_present
"1"> KEYS *
1) "people_now_present"
2) "temp_room1"

The keys need to match the IDs you used when registering the sensor.


pub use spaceapi as api;


Modifiers which can be injected by the application logic to change the state dynamically per request.


A listening server, which can later be closed.

A SpaceAPI server instance.

Builder to create a new SpaceapiServer instance.


A SpaceapiServerError wraps general problems that can occur in the SpaceAPI server.


Return own crate version. Used in API responses.

Type Definitions

Result type often returned from methods that can have hyper Errors.