Skip to main content

HTTP Interface

The HTTP interface makes it possible for the application to be controlled from other components like a web based frontend or a mobile application.

The server runs on the Raspberry PI on port 8080, and it does not have a public IP address which can be used to reach it. The interface is directly used by the Middleware component which also runs on the Raspberry and the way to initiate communication with the Raspberry is detailed there.

Endpoints​

There are currently 3 endpoints which can be reached through HTTP protocol:

  • POST /controller

This endpoint can be used to upload a new controller to the device. The controller is what essentially describes how the LEDs light up. It expects a request body in JSON which describes a controller. This format is described in the web-backend's static resources: http://localhost:8080/schema. It does nothing else but forwards the JSON to the core which then processes it. Currently, it does not handle any error and it always responds with 200 OK response status. It's unlikely to have any kind of errors because the web-backend validates the controller format, but it can happen. There's also a validation in the core library in development mode. In prod, it is disabled because it adds a substantial delay to the execution of the effect.

  • POST /sync

This endpoint can be used to initiate the music synchronization feature. To make it work it needs a controller to be uploaded which responds to music elements. It expects a request body in JSON with the following format:

  {
    "analysis": Track Analysis Object,
    "track": Track Object,
    "timestamp": Integer
  }

The analysis object has to describe a valid track analysis fetched from the Spotify API.

The track object has to describe valid track data fetched from the Spotify API.

The timestamp is the current epoch time in milliseconds. This is important so that the core is able to calculate the current progress of the music.

The endpoint handler only forwards this data to the core which then processes the data and acts accordingly. Just like the /controller endpoint it always responds with 200 OK status and doesn't handle any error which need to be addressed in the future.

  • POST /error

This endpoint can be used if any kind of error happened in the middleware component and it needs visualization. Calling this endpoint causes the LEDs to start flashing red which indicates the error.