Skip to content

API Reference

Jump to bottom
Ana Cristina Franco da Silva edited this page Jun 27, 2019 · 23 revisions

The MBP provides an API for the management of devices, adapters, sensors and actuators. Furthermore, an interface to trigger the binding of sensors and actuator is as well provided. Sensor and actuator values sent to the MBP can be retrieved.

To use the MBP API, basic authentication is employed to access the resources. For that, an authorization header is required in every client request, with exception for the POST requests "/api/authenticate" and "/api/users", which are used for authentication and creation of a new user. In the following example of the authorization header, the value "YWRtaW46YWRtaW4=" is a Base64 encoding of "admin:admin" (username:password).

Authorization: Basic YWRtaW46YWRtaW4=

Management of Devices
Management of Sensor and Actuator Adapters
Management of Sensors
Management of Actuators
Management of Application Settings

Management of Devices

  • Registering a new device. To register an IoT device (e.g., a Raspberry Pi) in the MBP, use the following request. The id of the registered device is returned in the response as the header location and in the response body (json-formatted).
POST /api/devices/ HTTP/1.1  
Content-Type: application/json  
accept: application/json

{
  "name": "Raspberry Pi",
  "macAddress": "123456789067",
  "ipAddress": "192.168.0.34",
  "formattedMacAddress": "12-34-56-78-90-67",
  "username": "pi",
  "rsaKey": "-----BEGIN RSA PRIVATE KEY-----\nMIIEogIBAAKC...\n-----END RSA PRIVATE KEY-----"
}
HTTP/1.1 201 Created  
location: http://localhost:8080/MBP/api/devices/5a033094c27074e37bbb198b  
Content-Type:
application/json;charset=UTF-8

{
  "id": "5a033094c27074e37bbb198b",
  "name": "Raspberry Pi",
  "macAddress": "123456789067",
  "ipAddress": "192.168.0.34",
  "username": "pi",
  "date": null,
  ...
}
  • Retrieving all registered devices. To receive a list of all registered devices in the MBP, use the following request.
GET /api/devices/ HTTP/1.1  
HTTP/1.1 200 OK

[
  {
    "macAddress": "123456789067",
    "ipAddress": "192.168.0.34",
    "name": "Raspberry Pi",
    "id": "596c7a7d4f0c58688e5aa6b1",
    "date": null,
  }, ...
]
  • Retrieving a device. To retrieve the information about a device (e.g., with registered id 596c7), use the following request.
GET /api/devices/596c7 HTTP/1.1
HTTP/1.1 200 OK

{
  "macAddress": "123456789067",
  "ipAddress": "192.168.0.34",
  "name": "Raspberry Pi",
  "id": "596c7",
  "date": null,
  "username": "pi",
}
  • Updating device information. To update the information of a device (e.g., with registered id 596c7), use the following request.
PUT /api/devices/596c7 HTTP/1.1

{
  "name": "Raspberry Pi",
  "macAddress": "127556789067",
  "ipAddress": "192.168.0.75",
  "formattedMacAddress": "12-75-56-78-90-67",
  "username": "pi",
  "rsaKey": "-----BEGIN RSA PRIVATE KEY-----\nMIIEogIBAAKC...\n-----END RSA PRIVATE KEY-----"
}
HTTP/1.1 204 No Content
  • Removing a device. To unregister a device (e.g., with registered id 596c7), use the following request.
DELETE /api/devices/596c7 HTTP/1.1
HTTP/1.1 204 No Content

Management of Sensor and Actuator Adapters

An adapter is the required software (e.g., python script) to bind sensors and actuators to the MBP. Examples to such adapters can be found in Adapter Scripts. Each adapter shall be composed of at least the files install.sh and start.sh. Furthermore, by including the files running.sh and stop.sh in the adapter, it allows the MBP to check if the adapter is currently running and to undeploy the adapter.

  • Creating a new adapter. To create a new adapter for a sensor or an actuator, use the following request. The id of the newly created adapter is returned in the response as the header location and in the response body (json-formatted).
POST /api/adapters/ HTTP/1.1
Content-Type: application/json  
accept: application/json  

{
  "name": "TemperatureSensorAdapter",
  "description": "An adapter for the LK temperature sensor",
  "service": {
    "name": "service-stub.conf",
    "content": "stub conf"
  },
  "routines": [{
    "name": "service-stub.py",
    "content": "service code"
  }]
}
HTTP/1.1 201 Created  
location: http://localhost:8080/MBP/api/adapters/5a0336ba972ca8734022d67c
Content-Type: application/json;charset=UTF-8

{
  "id": "5a0336ba972ca8734022d67c",
  "name": "TemperatureSensorAdapter",
  "description": "An adapter for the LK temperature sensor",
  ...
}
  • Retrieving all adapters. To get a list of all existing adapters, use the following request.
GET /api/adapters/ HTTP/1.1
HTTP/1.1 200 OK

[
  {
    "name": "TemperatureSensorAdapter",
    "id": "596c7c344f0c58688e5aa6b3",
    "description": "An adapter for the LK temperature sensor"
  }, ...
]
  • Retrieving an adapter. To retrieve an existing adapter (e.g., with id 596c7), use the following request.
GET /api/adapters/596c7 HTTP/1.1
HTTP/1.1 200 OK

{
  "name": "TemperatureSensorAdapter",
  "id": "596c7",
  "description": "An adapter for the LK temperature sensor"
}
  • Updating an adapter. To update an adapter (e.g., with id 596c7), use the following request.
PUT /api/adapters/596c7 HTTP/1.1

{
  "name": "TemperatureSensorAdapter",
  "description": "An adapter for the LK temperature sensor",
  "service": {
    "name": "service-stub.conf",
    "content": "..."
  },
  "routines": [{
    "name": "service-stub.py",
    "content": "..."
  }]
}
HTTP/1.1 204 No Content
  • Deleting an adapter. To delete an adapter (e.g., with id 596c7), use the following request.
DELETE /api/adapters/596c7 HTTP/1.1
HTTP/1.1 204 No Content

Management of Sensors

To register a sensor, it is necessary to register first:
(i) the device to which the sensor is connected to, and
(ii) the adapter, i.e., the required software (e.g., python script) to bind the sensor to the MBP.

  • Registering a new sensor. The following example uses the previously registered adapter (id = 596c7) and device (id = 596c7). The id of the newly created sensor can be parsed from the response header location or from the response body, which is in json format.
POST /api/sensors/ HTTP/1.1  
Content-Type: application/json  
accept: application/json  

{
  "name": "Temperature Sensor",
  "adapter": "<URL>/api/adapters/596c7",
  "device": "<URL>/api/devices/596c7",
}
HTTP/1.1 201 Created  
location: http://localhost:8080/MBP/api/sensors/596c7  
Content-Type: application/json;charset=UTF-8

{
  "id": "596c7",
  "name": "test_sensor",
  ...
}
  • Retrieving all sensors. To get a list of all registered sensors, use the following request.
GET /api/sensors/ HTTP/1.1
HTTP/1.1 200 OK

[
  {
    "id": "596c7a974f0c58688e5aa6b2",
    "name": "test_sensor",
    "_embedded": {
      "device": {
        "macAddress": "111111111111",
        "ipAddress": null,
        "name": "Test_Device",
        "id": "596c7a7d4f0c58688e5aa6b1",
        "date": null
      }
    }
  }, ...
]
  • Retrieving a sensor. To retrieve information about a registered sensor (e.g., with id 596c7), use the following request.
GET /api/sensors/596c7 HTTP/1.1
HTTP/1.1 200 OK

{
  "id": "596c7",
  "name": "test_sensor",
  "_embedded": {
    "device": {
      "macAddress": "111111111111",
      "ipAddress": null,
      "name": "Test_Device",
      "id": "596c7a7d4f0c58688e5aa6b1",
      "date": null
    }
  }
}
  • Updating sensor information. To update the information about a sensor (e.g., with registered id 596c7), use the following request.
PUT /api/sensors/596c7 HTTP/1.1

{
  "name": "Temperature Sensor",
  "adapter": "<URL>/api/adapters/596c7c344f0c58688e5aa6b3",
  "device": "<URL>/api/devices/596c7a7d4f0c58688e5aa6b1",
}
HTTP/1.1 204 No Content
  • Removing a sensor. To remove a registered sensor (e.g., with id 596c7), use the following request.
DELETE /api/sensors/596c7 HTTP/1.1
HTTP/1.1 204 No Content
  • Deploying the adapter for a sensor. To deploy the adapter for a registered sensor (e.g., with id 596c7) onto the device, to which this sensor is connect, use the following request. Once the deployment is done, the sensor values are sent to the MBP and can be visualized in the sensor dashboard.
POST /api/deploy/sensor/596c7 HTTP/1.1
HTTP/1.1 201 Created
  • Retrieving all sensor values. To get a list of all sensor values sent to the MBP of a registered sensor (e.g., with id 5b068), use the following request.
GET /api/valueLogs/search/findAllByIdref?idref=5b068 HTTP/1.1
HTTP/1.1 200 OK

{
  "_embedded" : {
    "valueLogs" : [ {
      "qos" : 0,
      "topic" : "sensor/5b068",
      "message" : "{\"component\": \"SENSOR\", \"id\": \"5b068\", \"value\": \"42\"}",
      "date" : "2018-05-30 10:48:41",
      "idref" : "5b068",
      "component" : "SENSOR",
      "value" : "42",
      "_links" : {
        "self" : {
          "href" : "http://192.168.209.189:8080/MBP/api/valueLogs/5b0e81898315295d360367b0"
        },
        "valueLog" : {
          "href" : "http://192.168.209.189:8080/MBP/api/valueLogs/5b0e81898315295d360367b0"
        },
        "sensorRef" : {
          "href" : "http://192.168.209.189:8080/MBP/api/valueLogs/5b0e81898315295d360367b0/sensorRef"
        },
        "actuatorRef" : {
          "href" : "http://192.168.209.189:8080/MBP/api/valueLogs/5b0e81898315295d360367b0/actuatorRef"
        }
      }
    }, {...}
  }
}

To retrieve sensor values so that they are ordered by date, where the first value was the last value received, use:

/api/valueLogs/search/findAllByIdref?idref=5b068&sort=date,desc

To retrieve only the last sensor value, use:

/api/valueLogs/search/findAllByIdref?idref=5b068&page=0&size=1&sort=date,desc
  • Undeploying adapter of a sensor. To undeploy the adapter of a registered sensor (e.g., with id 596c7), which is running in the corresponding device, use the following request. Once the undeployment is done, the sensor values will not be sent to the MBP anymore and the adapter will be deleted from the device.
DELETE /api/deploy/sensor/596c7 HTTP/1.1
HTTP/1.1 204 No Content

Management of Actuators

see management requests for sensors, replace /sensors with /actuators

Management of Application Settings

There are some application-wide settings that can be changed by the user during runtime. This can be done with the following requests.

  • Retrieving application settings.
GET /api/settings HTTP/1.1
HTTP/1.1 200 OK

{
  "brokerLocation": "REMOTE",
  "brokerIPAddress": "129.69.185.190"
}
  • Changing application settings.
POST /api/settings HTTP/1.1
Content-Type: application/json
accept: application/json

{
  "brokerLocation": "REMOTE",
  "brokerIPAddress": "129.69.185.190"
}
HTTP/1.1 200 OK

Universität Stuttgart - MBP Team 🔧

MBP logo

Clone this wiki locally