Developers' quick start guide

A comprehensive guide to the flespi platform API.

Essentials

Any operation with the flespi platform can be performed via API; most operations are also possible via the flespi panel GUI. The purpose of the flespi API is to give a possibility to consume, transform, enrich, store, analyze, and forward telemetry data from versatile GPS tracking devices in a unified JSON format with normalized parameters names.

Types of API

Since flespi is a lot more than a pipeline for telemetry data consumption, but a fully-fledged telematics platform, its API covers all the modules and all the functionality available to the users. Below is the detailed structure of the flespi API:

  • platform — administrative operations (tokens, logs, subaccounts, etc.)
    • tokens — access permissions to the platform
    • logs — records about all events happening on the platform
    • subaccounts — building the accounts hierarchy
    • webhooks — actions triggered by specific events 
  • telematics hub — the core telematics functionality
    • calculators — data aggregation and analytics
    • channels — data ingestion
    • devices — data storage, telemetry, device management, etc.
    • groups — device organization
    • modems — device management via SMS
    • plugins — data transformation and enrichment
    • protocols — supported telematics protocols
    • streams — data forwarding, integrations enablement
  • storage — low level storage management
  • mqtt broker — flespi MQTT broker management

Examples

In the examples below, we imply that you have already connected at least one device to flespi and started receiving messages from it. If not, please follow this quick start guide to do that or simulate a device.

Getting device messages

If you are using flespi, you want device messages in an easily digestible format. You can get received messages from specific or all devices:

https://flespi.io/docs/#/gw/devices/get_devices_dev_selector_messages 

flespi api get device messages

results in

flespi api get device messages result

Note: if you need to get new messages in real-time, consider using MQTT or streams.

Device management (sending commands)

Flespi empowers a fully-functional bidirectional communication — not only receiving messages, but also sending commands. Should you decide to instruct your device to change behavior, you simply use a universal POST command request: 

https://flespi.io/docs/#/gw/devices/post_devices_dev_selector_commands 

The command will attempt to execute immediately and will succeed if the device is online. 

flespi api send command to device

If you need to execute a sequence of commands in a specific order or your device is currently not connected, place commands in the right order to the commands queue:

https://flespi.io/docs/#/gw/devices/post_devices_dev_selector_commands_queue 

Read more about commands and settings in a dedicated article.

Obtaining telemetry

Getting the last state of all device parameters with a single request gives an easy way to update different metrics your solution relies on with up-to-date values.

https://flespi.io/docs/#/gw/devices/get_devices_dev_selector_telemetry_telemetry_selector

flespi api get device telemetry

results in

flespi api get device telemetry result

Again, to get immediate telemetry updates, subscribe to the respective MQTT topic: flespi/state/gw/devices/<device_ID>/telemetry/#.

Getting aggregated data

You can extract not only individual messages via API but also aggregated message intervals calculated by the flespi analytics engine.

Get the calculated intervals for a specific device using the following API request:

https://flespi.io/docs/#/gw/calculators/get_calcs_calcs_selector_devices_calc_devices_selector_intervals_calc_device_intervals_selector 

flespi api get intervals for device

results in

flespi api get intervals for device result

All the possibilities of the flespi API are available via the interactive APIbox tool.

REST selectors

Below are the examples of REST API selectors that can make your REST API requests more efficient.

‘all’ keyword

“all” is used to apply the request to all instances of some entity type in the current account.

For example,

GET /gw/devices/all

will get all devices in the current account.

Important: if you decide to perform a request like GET /devices/all/messages and your devices store quite a lot of data, your account may be blocked because of too many REST API calls per minute (see restrictions).

Filtering by parameter

You can specify the parameter value to be matched for the request to apply to the given entity.

For example,

GET /gw/channels/protocol_name=teltonika

will get the list of all channels with “teltonika” protocol.

Note: the fields available for filtering differ for different entity types and can be found in the appropriate section of the documentation.

For instance, if you use a plugin to attach a static field (e.g. 'driver') to the device, you can then use the following request to filter the devices with the specific field value:

GET /gw/plugins/all/devices/fields.driver=value

Filtering by time frame

You can specify the "from" and "to" parameters to get the data for a specific time period only. For example:

GET /dw/devices/{dev-selector}/messages?data={"from": 1111111111, "to": 2222222222}

The values in the "from" and "to" fields should represent a valid UNIX timestamp.

Filtering by specific ids

You can list the specific IDs on the items you want to apply the request to.

For example,

POST /gw/devices/1,2,3,4/commands

will send commands into the devices with the specified IDs.

Note: logical AND condition is applied to comma-separated lists of values. 

Using wildcards

You can use wildcard chars * and ? in values in the request.

For example,

GET /gw/devices/configuration.ident=1234*/telemetry/all

will get the telemetry for devices with idents matching the wildcard mask.

Logical conditions

You can use the logical conditions to check the values of certain boolean parameters and apply requests to the matching entities.

For example,

GET /gw/channels/enabled=true

will give you a list of channels in active mode (use 'false' in the selector to get the list of inactive channels).

Hint: you can always check what specific filtering options are supported in the given selector, by expanding the selector info in APIBox:

apibox rest selector

MQTT

The MQTT protocol ensures fast and secure message delivery, so you receive an event message in MQTT session once it appears inside the flespi platform. Below are some examples of specific uses of MQTT in flespi.

Flespi state

flespi/state/# is a special system topic in your flespi account that lets you instantly get a number of metrics about all the items (e.g. channels, connections, storage, etc.) via MQTT.

For example, you can get the device telemetry (the latest values of all device parameters) by subscribing to a single topic: flespi/state/gw/devices/{device_id}/telemetry/#:

flespi state mqtt topic

Read more about state.

Events 

You can catch specific events related to the flespi items (created, updated, deleted, deactivated, etc.) by subscribing to the proper MQTT topics. For example, to catch that the device accepted the new setting value, you can subscribe to flespi/log/gw/devices/{device_id}/settings/+/accepted to get updates:

flespi mqtt topic event

Another way of catching MQTT events is webhooks — they allow performing HTTP calls to external third-party services or to the flespi platform triggered by a specific value or value change in an MQTT topic. 

Read more about events.

Logs

All the logs in flespi are also accessible via MQTT, which makes it easy to catch specific events by subscribing to the proper logs and filtering by specific event codes (if necessary):

flespi mqtt topic logs

MQTT Board for debugging

It’s convenient to use the MQTT board tool to play around with the MQTT topics before you utilize them in your solution. 

Note that you can subscribe to the specific topic related to a specific flespi item straight from this item’s Info tab -> MQTT section:

subscribe with mqtt board to flespi topic

Once you click the Subscribe to MQTT Board icon next to the desired topic, the MQTT Board tab will open on the pane. You will simply need to click the Play (▶) button to subscribe and monitor this topic:

mqtt board subscribe

MQTT Topics directory

To explore the flespi MQTT topics in their entirety, check the exhaustive list available in the left-side menu of the flespi panel:

flespi mqtt topics directory

Troubleshooting

You can check the status of execution of your REST API requests in the platform logs (flespi panel -> Platform logs in the left-side menu):

rest api platform logs


See also
Obtain telematics data from eView devices via API in 5 easy steps.
Obtain telematics data from Ruptela devices via API in 6 easy steps.