Sensor management API – Info

As a manufacturer of sensors, you need a powerful API to allow your customers to manager their sensors.

Problem

Imagine that you work at a sensor manufacturer. Your company makes different types of sensors and sells these. Your job is to create a REST api to manage all of these sensors. Customers, that means companies that buy the sensors, need to be able to manage these sensors. The sensors also need to be able to fetch some information to manage themselves. Managing these sensors has different aspects: 

Sensors

Users need to be able to read, add update sensors.  Every new sensor added comes with a base factory firmware and a base configuration so that the sensor can receive events that trigger either a configuration update or a firmware update. 

There is no endpoint required to delete a sensor. Once a sensor has been manufactured, it’s intended to stay for a long time. 

Users should be able to upload sensors with csv files containing up to 500 new sensors each day. 

Tasks

Another aspect is tasks. If you want to update the firmware or the configuration of any of these sensors, you need to schedule a task to do so. A task also gets a unique number. When a task is scheduled for a particular sensor, the status of the target sensor needs to be updated as well, indicating that the sensor is busy with a task. Tasks can be queued and thus a sensor can make a request to fetch the next task that is waiting. Tasks can be deleted/cancelled. 

A task can be updated. If a sensor is done with a task, it needs to be updated. Users of the API need to also be able to see the history of tasks for a certain sensor and whether or not that task was a success, a failure or if it was cancelled. 

Files

The last aspect is file management. When a configuration update task is created, users need to specify which configuration file needs to be uploaded. So these files need to be managed and stored. A user needs to be able to look at all the configuration files and needs to be able to upload new files.

Use case 1: Endpoint to get sensor information

Create a REST endpoint that allows you to see the information of one sensor. The response should look like this: 

{
  "serial": 123456789098789,
  "type": "TS50X",
  "status_id": 1,
  "current_configuration": "some_oonfiguration.cfg",
  "current_firmware": "FW:23-09-2022:03",
  "created_at": "2022-03-31 11:26:08",
  "updated_at": "2022-10-18 17:53:48",
  "status_name": "Idle",
  "next_task": null,
  "task_count": 5,
  "activity_status": "Online",
  "task_queue": [211345600, 3343123345] 
}

Use case 2: Endpoint to add a new sensor

Create a REST endpoint to add one new sensor. The ID of the sensor needs to be unique for all sensors that are developed by your own company. Every new sensor has the base firmware and the base configuration installed.

A sensor has an ID, a type, a status and status id, a current configuration installed, a firmware version, a creation date and a date where it was last updated. It also has an activity status. It is up to you to decide how the request will look like and how the actual sensor model looks like. Not every fields in the model needs to be represented in the request to add a new sensor. 

Additional information

Status

A sensor can be in one of the next statuses:

Status name Status id Description
Idle 1 The sensor doesn’t have any tasks
Awaiting 2 A task has been scheduled, the device is waiting for execution
Updating 3 The device is doing an update

 

Activity status

A sensor can have the following activity statuses:

Status name Status id Description
Online 1 The sensor is online and capable of sending information
Disconnectd 2 The sensor is not online and cannot send information
Error 3 The sensor is in an error state and cannot function normally

Use case 3: Endpoint to update activity status

Create an endpoint for updating the information of a sensor. This endpoint is for sensors as they should be able to update if they come online. This request is more of a ‘ping’ so that the server knows the sensor is online. 

Use case 4: Endpoint to create sensors in bulk

Create an endpoint to bulk create sensors with csv files containing up to 500 new sensors each day.

Use case 5: Endpoint to get task information

Create an endpoint to request information about one specific task. The response should look like this:

{
  "id": 16624171,
  "sensor_serial": 12345678909789,
  "type": "update_firmware",
  "status_id": 2,
  "attempt_count": 3,
  "created_at": "2022-10-17 16:00:07",
  "updated_at": "2022-10-17 16:49:39",
  "file_id": "a3e4aed2-b091-41a6-8265-2185040e2c32",
  "status_name": "Completed"
}

Use case 6: Endpoint to create a task

Create an endpoint to create a new task. When a task is created, it is ‘pending’ until the sensor picks it up and performs the task. A task has the following information: id, sensor ID, type, status id, attempt_count, created at, updated at, file id, status. 

Additional information

Task type

A task can have be one of 2 types:

Type Description
update_firmware A task to update the firmware
update_configuration A task to update the configuration

Both types of tasks actually need a file (either the firmware installation file or the configuration file) to be able to do their job. That is why the API is showing a file_id, which is a reference to an existing file.

Status

A task can be in one of the next statuses:

Status name Status id Description
Pending 1 The task is waiting to start
Completed 2 The task has successfully completed
Error 3 The task was either interrupted by an error or it completed causing an error
Ongoing 4 The task is ongoing

Use case 7: Endpoint to delete a task

Create an endpoint to delete or cancel an ongoing task. The task is not really deleted, just the status is updated. A cancelled task can’t be uncancelled. Users need to recreate a cancelled task if they accidentaly cancelled it. 

If the task was ongoing, then cancelling a task should also update the status of the sensor. Normally, the sensor should be notified as well, but we will leave that out of scope for now.

There are different ways of implementing this use case, each with their own pro’s and cons. Experiment away!

Use case 8: Endpoint to update the status of a task

Create an endpoint to the status of a task. Just like with the previous use case, don’t forget to also update the status of the sensor. 

Evolutions

What are evolutions again? Evolution are extra challenges which you can complete after you have done the base challenges. Evolutions are exactly what you think they are: they are evolutions of the problem, changes in requirements of users and stakeholders. They are meant to test the design of your solution.

Evolution 1:

Authorisation and security

We completely missed the security aspect of this API! Right now, everybody can access all of the endpoints and see information about all the sensors, even though they do not own these senors. 

Figure out a solution to secure the endpoints and to grant authorisation for different users. Specifically the authorisation should only allow people who own or repersent a company that owns sensors to be able to see information about those sensors and the tasks. Obvioiusly, users can only create tasks for sensors they own.