mDash service REST API reference

Overview

mDash provides REST API for programmatic device management. You can create, modify and delete your devices programmatically. Also, each RPC function defined on a device, gets visible not only via MQTT, but via the HTTP/REST as well. For example, if you have defined custom RPC function GetTemperature on your device, there is a unique URL created for it, and you can call it using any HTTP client.

Key-based authentication

REST API calls must be authenticated by sending an Authorization: Bearer API_KEY HTTP header, or by appending the ?access_token=API_KEY to the request. POST API calls should also have a Content-Type: application/json header. Access keys can be managed on the "Keys" tab on the mDash UI. There are several types of access keys:

  • Master key - for you. Used to give root access to the REST API.
  • Device key - for your customers. Gives a restricted access to a single device.

How to get an API key

  • Login to mdash.net
  • Click on "Keys" tab
  • Click on the API key to copy it to the clipboard

Master key API

In the following reference, a https://mdash.net/api/v2 prefix must be added to all mentioned URLs.

Type URL Params Description
GET /devices - Return a list of all created devices
POST /devices - Create a new device and return it
POST /devices/:id {"shadow": {...}} Modify device shadow, return modified device
DELETE /devices/:id - Delete device
POST /devices/:id/rpc/:func {...} Call device's RPC function
GET /devices/:id/rpc/:func - Call device's RPC function with no params
GET /keys - Return a list of all API keys
POST /keys - Create and return a new API key
DELETE /keys/:id - Delete an API key
GET /data {"skip":0, "limit":100, "filter":"temp"} Get stored data. skip is the number of records to skip (if negative, counts from the end), limit is the number of records to return (max 5000), filter is a substring for topic or message.

Device key API

This is a restricted API, intended to be given to the end-customer. In the following reference, a https://mdash.net/api/v2 prefix must be added to all mentioned URLs.

Type URL Params Description
GET /device - Return device object with all information stripped out, except two sections in the device shadow: state.desired.app and state.reported.app. The intention is to give an ability for the end-customer to control and view the device in a restricted way.
POST /device {"shadow": ...} Change device shadow. Again, only state.desired.app and state.reported.app are available
GET /data {"skip":0, "limit":100, "filter":"temp"} Get stored data for a topic that start with db/DEVICE_ID/