Designing a REST API

A project log for Scintilla

We're building a low-cost, commercial grade gas sensor platform in order to democratize air quality data.

chris-del-guercioChris Del Guercio 09/22/2016 at 17:390 Comments

This week I spent a good chunk of time designing the spec for the sensor data REST API. The API has been designed to be used not only by our product, but also by other sensor products. The main goals of the API are to 1) provide a simple yet powerful interface for sensors to upload data and 2) be designed so that every useful way that someone would want to query the data can be done efficiently.

Above is the awful diagram that I crammed into a Google Slides page. The top starts with the Platform and Sensor tables, which formalize the sensor platform and the actual sensors within the platform. For example, Scintilla's product would be a Platform, and the SPEC sensors that we are using would exist in the Sensor table and be referenced by our Platform entry. A Deployment is a user defined group of Devices. This would be useful for instances where a user would want to aggregate data from many devices in either a consolidated dashboard view, or in a downloaded report. The Device table holds references to actual devices in the field. Each Device has a private device key that it uses to authenticate the data that it sends to the server. We take data integrity very seriously and our resident computer security PhD student Eric Gustafson is working on making sure that the device keys are safe from prying eyes. Readings represent the raw readings that the sensor takes. They can be point values or averages and they can be of any unit. Readings taken at the same time are sent in bundles called ReadingGroups. These groupings can later be utilized to calibrate many readings against each other to compensate for things like cross interference or temperature and humidity skewing the data. For instance, a device might send out a ReadingGroup that contains one Carbon Monoxide Reading, one Temperature Reading, and one Nitrogen Dioxide Reading. It could be the case the the CO sensor has a known cross interference with NO2, so the CO Reading might be decreased based on how much NO2 was detected. In addition, both CO and NO2 sensors likely have documented biases that change with temperature, so those Readings could be calibrated against the Temperature Reading. How Readings are grouped is completely up to the client. CalibratedReadings are Readings that have had post processing done on them. How this is done is also completely up to the client.

This is only v0.1 of the API. The next step is to get our product communicating with a server using this API and see how it works in practice.