REST API guidelines

flespi platform uses REST API as a standardized and reliable way to transfer data over the Internet. REST defines common rules to formulate unambiguous and complete HTTP-requests from client to server. The main idea behind REST is clarity — the action to be performed is apparent from HTTP-request method, URL, and optional parameters.

These REST API guidelines are relevant for:

An alternative to receiving platform event messages via REST API is MQTT API.

Here are the basic examples of REST API calls:

Example 1.

get_protocol.jpg

Example 2.

post_channel

Example 3.

remove_devices

The example response to the following request:
Get ID and name of channels with IDs 1 and 2 where channel 2 does not exist response_structure

You can control API access using token ACLs.

API guidelines FAQ

Log in to flespi.io with one of your social accounts and go to the Documentation tab. Documentation is interactive — you can build a REST API request, execute it by clicking “Try it out” button, and view the response from the request description page.

API guidelines FAQ 0

The REST API call is based on a HTTP request, so you can perform it in a number of ways:

REST API request itself consists of:

Method

Method is a one-word HTTP-request attribute telling what kind of maniulation will occur. HTTP/1.1 standard includes 8 methods, however REST uses 4 of them.

  • GET — to request existing data
  • POST — to create new instances
  • PUT — to edit existing instances fields
  • DELETE — to remove items

URL

REST specifies next rule for resource location:

../objects/{specify objects}/sub_objects/{specify sub_objects}..

To specify objects flespi products API uses the term {obj.selector} described below (Note, that all requests support multiple objects processing. This means that you can review, change, delete or create several objects in a single request):

  • keyword “all” – selects all possible objects
  • list of ID's, e.g. “1,2,5” – selects only objects with specified ID's
  • filtering parameters separately defined for every type of request according to object's fields

Request variables

There are only 2 optional request variables that can appear in a query string or multipart/form-data:

  • data – json-object string with fields to be passed to target-instance (or json-array in case of multiple target-instances)
  • fields – comma-separated list of object fields to be returned in response

Headers

The only required header is Authorization:

Authorization: FlespiToken abcdefg1234567890

It consists of header name “Authorization”, keyword “FlespiToken” to state that request addresses one of flespi services, and token string provided to the flespi client after successful registration.

Token is an identification string added to REST API request to inform flespi platform on who is the author of the request. Manage tokens on Tokens tab in your personal account and with flespi platform API. You can manage API tokens restrictions using Access control lists (ACL). Also check our video tutorial on how to create a flespi token.

API guidelines FAQ 3

Response to REST API request consists of:

HTTP response code:

  • 200 – OK. Result of requested actions is in response body.
  • 400 – Incorrect parameters. This means that not all required parameters were included or some parameters are invalid.
  • 401/402 – Authorization problems. 401 code means that “Authorization” header is missing and 402 code means that pointed token has insufficient permissions.

Response body — a JSON-object with 2 fields: result and errors.

  • result is a JSON-array of instances successfully modified by REST API request, including fields listed in fields request variable.
  • errors is a JSON-array of error instances.

Code 200 informs that the request was successful, while empty result list means that no objects were affected. This may happen in case of very specific filtering parameters. E.g. for request

GET flespi.io/channels/name=test

empty result list means that there is no channel called “test”.

Code 403 means that the platform blocked the token or the customer. The most likely reason is exceeding the limits: too many API requests per minute, too much traffic from devices, too many connections to the channel etc. See the complete list of limitations here.

Selector specifies the resource location in request URI. Selector can be:

  • keyword "all" – selects all possible objects
  • list of ID's, e.g. "1,2,3" – selects only objects with specified ID's
  • filtering parameters separately defined for every type of request according to the object fields

E.g. to select channel names starting with letter “a”, operating via a protocol with id=1, with logs lifetime greater than an hour, and opened to new connections, the selector string looks like

https://flespi.io/gw/channels/name=a*,protocol_id=1,logs_ttl>3600,enabled=true

Messages in a channel are stored in a sequential bucket called abque — asynchronous batch queue. Thus, messages have to be read sequentially beginning from the most recent. “Get messages” request will return next_key parameter to use in the next request.

An alternative to the REST API in receiving platform event messages is MQTT API.

If you want to view messages from devices in UI-mode you can use a Toolbox.

API guidelines FAQ 8

No, the system automatically assigns ID to a newly created object. Use "name" property to easily find and use platform objects.

Connections from devices to flespi gateway can be operated with gateway connections section. You can view active connections with GET request, close specified connections with DELETE request.

Connections can also be reviewd and deleted in UI mode in channels card.

API guidelines FAQ 12

All new connections are also included in the channel logs available from channels panel and via REST API.

A container represents a simple key:value database where a key is a 32-bit unsigned integer and a value is a custom JSON object. Abque is short for "asynchronous batch queue" which is a queue-type storage. A message is a JSON object with any set of custom fields of up to 8MB in binary size. Abque is designed for multiple-writers/single-reader mode. To get more understanding about storage types see the blog article about flespi storage.