We need to change
The flespi platform has been evolving and mutating actively in the past few years — some concepts changed, new ones emerged, some others became extinct. Flespi paradigm is device-centric — meaning that flespi device is the ultimate point of contact when dealing with storage, analytics, settings, etc.
Since many of the flespi users rely on device API in their projects, we try to keep it stable. However, sometimes long-term platform development perspectives require targeted changes, one of which became the topic of this article.
New device structure
The key attributes of any device in the flespi platform are device type and device configuration. The device configuration object is the new entity that we’ve recently introduced. Device type defines the schema of the device configuration. So to create or modify the device you should respect this configuration schema. To get this configuration schema for a given device type, perform the following REST API request: https://flespi.io/docs/#/gw/!/protocols/get_protocols_protocol_selector_device_types_devtypes_selector
Once you have the configuration schema, you can create a new device of a given type using the same REST API request as before: https://flespi.io/docs/#/gw/!/devices/post_devices:
Please note the configuration object that may accept any fields that comply with the given device type schema.
Device configuration is a JSON object with a set of fields. Each configuration field corresponds to a certain device feature. The “system” fields usually include one or some of the following:
ident [string] — unique device identifier, like IMEI, serial number, etc. Used to identify incoming channel messages and store it into the device storage
phone [string] — device phone number or SIM card ICCID serial number used to receive SMS messages or send commands over SMS
password [string] — device password used to authenticate incoming connections to the channel
sms_password [string] — device password used to authenticate SMS commands sent to the device
Note: the ident value must be unique among all devices of the same protocol; the phone value must be unique among all devices in the account; all listed “system” fields will always have a string type.
Here is an example of a JSON object for the new device:
Don’t confuse! During the transition period devices also contain "ident" and "phone" attributes as per the old schema — these are obsolete and should not be used anymore. They will be deleted in the near future — on September 4, 2019 (see details below).
Moving ident and phone fields into a separate configuration object also affected the selectors used to get device via REST API. Previously, you could find devices by an ident mask like this:
GET /gw/devices/ident=mask*
Now the request looks like this:
GET /gw/devices/configuration.ident=mask*
The configuration object allows for more control over the parameter values, e.g. the schema may define if the ident (or other fields) should contain numbers only or should be of a certain length (or no longer than a certain number of characters), etc. If a certain device type requires some “secret_key” instead of a password, it’s possible to define one in the right place of a given device type schema. This approach allows maintaining a well-defined yet flexible architecture for efficient platform growth.
New subscriptions
Changes also happened in the streams subscriptions mechanism — in essence, the term “subscription” is no longer used, you simply assign devices or channels to a specific stream:
The selectors are now:
POST /streams/{stm-selector}/channels/{channel.subscr-selector}
and
POST /streams/{stm-selector}/devices/{device.subscr-selector}
instead of POST /streams/{stm-selector}/channels/ and POST /streams/{stm-selector}/devices/ (see other methods here).
[Important] Take your time but don’t postpone
We understand that you need time to apply the new API across your projects. That’s why the old version of the devices and stream subscriptions API is fully operational for the next two months and will be removed in several steps:
On August 7, 2019, starting from 12 pm UTC we will remove “ident” and “phone” from default fields of all related REST requests and from MQTT retained topics at flespi/state/gw/devices/+/{ident,phone}. You will still be able to use it specifying the exact list of such fields in each REST API request using ?fields=...,ident,phone,... query string parameter.
Also on August 7, 2019, starting from 12 pm UTC we will add an error message to all responses that will be using deprecated device fields and old subscriptions methods.
On September 4, 2019, starting from 12 pm UTC we will completely delete the old-style API and move forward with the new one, so plan your transition wisely.