Intro
Getting the data from versatile telematics devices in a convenient and unified format for the needs of your solution is the primary purpose of flespi's existence. In other words, whatever GPS tracker you use, you can get messages in a JSON format with consistently named parameters by executing the same API call. As a result, you are supplied with the processed data from your devices in real time to wrap the business logic around it, maximize its value and meaning, and present it to the customer.
This is a simplified concept of what flespi is capable of. Below we will elaborate on the true power of the flespi API, its typical uses, and practical advice based on our and our users' experience.
Frequent uses of the flespi API
Flespi REST API is logically divided into the platform, gateway (you most likely want this one), storage, and MQTT broker APIs. However, here we want to highlight only several sections to highlight the scope of possibilities the API has.
Since further requests will refer to a specific item (channel, device, etc.), we need to know their IDs first. The following requests let you get the list of channel IDs and device IDs (use “all” in the selector to get the entire list).
Consuming fresh data (getting device messages)
If you are using flespi, you want device messages in an easily digestible format. You can get these messages either from a channel (messages from all devices connected to the channel):
https://flespi.io/docs/#/gw/channels/get_channels_1_ch_selector_messages
results in
or from a device (messages from a specific device only):
https://flespi.io/docs/#/gw/devices/get_devices_dev_selector_messages
results in
Note: if you need to get new messages in real-time, consider using MQTT or streams.
Managing device behavior (sending commands)
Flespi empowers a fully-functional bi-directional 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.
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
Getting the latest object state (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
results in
Again, to get immediate telemetry updates subscribe to the respective topic: flespi/state/gw/devices/<device_ID>/telemetry/#.
Using aggregated metrics (requesting calculated intervals)
In short, you can extract not only individual messages via API but also aggregated message intervals calculated by the flespi analytics engine.
Note: If you are not familiar with the analytics module, there’s a lot of homework to do before you can efficiently consume the results generated by the analytics engine.
Get the calculated intervals for a specific device using the following API request:
results in
A lot more
All the possibilities of the flespi API are available via the interactive APIbox tool.
REST vs MQTT
What we showed above are some examples of REST API requests that you can execute to perform specific tasks.
For those who would prefer push-based data consumption (as opposed to pull-based REST), flespi offers MQTT API. You can subscribe to specific MQTT topics to get the proper pieces of data.
Note: MQTT API is a great way to get real-time data updates. Keep in mind that sending commands is only possible via REST API or REST API via MQTT.
Tips to optimize performance
Limit the count of requested messages (or intervals) to avoid unnecessary load.
Explore the differences between settings and commands, and between real-time commands and command queue depending on your device(s) availability, mode of operation, and other factors to optimize communication and ensure predictable behavior.
Use commas in selectors to specify multiple items, e.g. curl -X get --header 'Authorization: XXXXXX' 'https://flespi.io/gw/devices/1,2,3,4,5/telemetry/position,din'.
Use filters in curl requests to shrink output to the most relevant values (see more details here), e.g. curl -X GET --header 'Authorization: FlespiToken XXXXX' 'https://flespi.io/gw/devices/1820833/messages?data={"count":100,"filter":"ident="354018111044933"”}'.
Adjust TTLs (messages_ttl, commands_ttl, intervals_ttl) to manage the amount of stored data.
Use ACL tokens to grant access to specific parts of the platform.
Organize the items in your account by customer or project using the hierarchical subaccounts structure.
***
Above we highlighted just a fraction of the flespi API capabilities. Obviously, you can also modify and delete any items stored on the platform (avoid the “delete all devices” request since it cannot be undone;). Any operation with the platform entities can be performed via API while also being reflected on the flespi panel interface. Flespi is a one-stop destination to effectively handle communication with versatile hardware, apply analytics, and provide easy data access.