12 July, 2018

MQTT scores again: flespi REST API over MQTT

How to use flespi HTTP REST API over MQTT and when not to do that.

http vs mqtt

Above is the list of the most spectacular standoffs in the world for a flespi programmer. Epic battle, isn’t it? A techy person might remark that HTTP and MQTT are used in different applications, that each protocol is good in its sphere, and that Superman has no chances. 

Scales tip in favor of MQTT

We decided to use MQTT as the main internal communication technology for our platform and this solution has fully proven itself. MQTT provides a very fast event-driven architecture to receive new messages from flespi.

We don’t mean to say that we leave HTTP on the sidelines. Originally, most services inside flespi operated over HTTP REST API and we even wrote our own HTTP framework. We also have an HTTP channel and implemented integration with Wialon over the HTTP stream.

Until recently HTTP was the only protocol to manipulate the platform via REST API. But now we open flespi REST API for use over MQTT protocol.

A tech-savvy reader would reasonably note: “Wait a minute! REST API implies client-server model and MQTT communication type is publish-subscribe. Something’s not right!”. Here is a simple scheme of the client-server request:

client server architecture

We can see that both the client and the server can send and receive data. In MQTT publish-subscribe terms it means the following:

publish subscribe architecture

Conclusion: server-client request with MQTT client implies publishing the request and subscribing for a certain topic to receive the response.

Mapping HTTP to MQTT

Let’s revise how the HTTP REST API call works to see how can we implement the same scenario in a publish-subscribe manner. The most complex HTTP REST API call to flespi consists of:

  • authorization header: who are you?
  • path: what object do you want to affect?
  • method: what do you want to do with that object?
  • data (optional): what exactly to do?

Consider example 2 at REST API page (request to create a new channel):

curl -X POST --header ‘Auth Token’ -d ‘[{“name”:”first”,”protocol_name”:”test”}]’ ‘https://flespi.io/gw/channels’

An attentive listener might note that the MQTT client authorizes on connection, so one does not need to send an Authorization token with every request. Profit!

So we are left with the method, path, and optional data parameter in the HTTP request and topic and payload in MQTT terms. Let’s separate it into required and optional: method and path go to the topic and optional data goes to the payload that can be empty. 

To perform the example request for creating a new channel do the following:

  1. subscribe to the topic flespi/rest/post/gw/channels
  2. publish payload [{"name":"first","protocol_name":"test"}] to the topic flespi/rest/post/gw/channels
  3. receive REST API response on subscription

It looks like this:

mapping http to mqtt

That’s it. Almost as easy as clicking the “Try it out!” button in our interactive documentation. 

 You might note that the MQTT client published and subscribed to the same topic. The most advanced flespi customers that use MQTT v5.0 can use a special response topic parameter to define a different topic to forward the response to.

 Benefits of MQTT API

  1. One-time authorization. No need to push an authorization token for each request.
  2. Solid architecture. No need to use different types of API to build your fast panel or dashboard.
  3. High performance. Good to use on big quantities of requests: you use a single connection with multiple subscriptions.

Important: the described method is a wrapper. It means that behind the scenes your MQTT request will be proxied to an HTTP request. So we do not recommend using it to receive large volumes of data (like stored messages for devices) since MQTT is intended to efficiently process many small requests.

Be inquiring and reasonable — it pays off.