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-fleged 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.)
- gateway — the core functionality of the telematics hub
- 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 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.
Device management (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
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
results in
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:
results in
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,
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 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,
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:
REST vs MQTT API
It is possible to "wrap" a REST API request into the MQTT notation.
Publish to the flespi/rest/{method}/{api-uri} topic to perform REST API call to the flespi platform. {method} should be valid for the specified {api-uri}. Optional data parameter may be passed as MQTT message payload. MQTT v5.0 accepts "response topic" parameter with the indication of the topic to which to publish a response to API call. Otherwise, the response is published to the same topic.
Additional user property "response_cid" allows redirecting the response to another subaccount. This is a special feature helpful when you want to perform an API call on the top-level (from the master account) and redirect its result from the flespi broker directly to one of the subaccounts.
One more feature is the "response_chunked" user property. If it's "true", the response will be chunked in multiple MQTT messages. A message with the specified "http_code" user property is the indication of the last chunk (message).
For example, to execute a request to create a new channel we need to:
- subscribe to the topic flespi/rest/post/gw/channels
- publish payload [{"name":"first","protocol_name":"test"}] to the topic flespi/rest/post/gw/channels
- receive REST API response on subscription
Benefits of MQTT API
- One-time authorization. No need to push an authorization token for each request (MQTT client authorizes upon connecting).
- Solid architecture. No need to use different types of API to build your fast panel or dashboard.
- High performance. Good to use on big quantities of requests: you use a single connection with multiple subscriptions.
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):
