api module’s design

This module listens to HTTP REST requests, and relays them into MQTT, so that other modules can handle and respond to them, and after they handle it, api module listens in MQTT for the response and it sends it back to the HTTP requester.

In this section we will explain what is the design behind the HTTP REST requests and MQTT messages.

HTTP REST

Base path for REST HTTP requests:

  • /api

Division into two routes so that the separation between reading and writing resources is clear:

api/in

REST

HTTP method: PUT

URL: api/in/<agent>/<subpath>

  • <agent>: is the module to which you want to send data. For example sp_command/status or sp_command/status/w.r3.c4.

  • <subpath>: is the subtopic of mqtt to which it will be published. This is specific for each module. That is, the <subpath> for sp_command is different from any other. If you want to publish to several subtopics, a subtopics field can be included in the data sent as described below.

Specifying to which agent to send the message prevents all other agents from receiving it. Subpath(s) has a specific form depending on which agent is sent so that it can adapt to the functionality of each. For example, our agent (sp_command) will allow you to identify smartplugs directly by ID or filter smartplugs by row and column but other agents may have completely different functionalities.

URL Examples:

  • api/in/sp_command/m1

  • api/in/sp_command/g0

  • api/in/sp_command/w.r1.c2

  • api/in/sp_command/row/1

  • api/in/sp_command/column/2

PUT Data:

{
    "subtopics": [
        "<subtopic:1>",
        "<subtopic:2>"
      ],
      "payload": "<payload>"
}

or

{
     "payload": "<payload>"
}

If there are not several subtopics and the message will be sent directly to what is specified in the URL, the list may be empty or omitted. If not, the message will be sent to each topic consisting of: <agent>/<subpath>/<subtopic>.

MQTT

In order to understand how MQTT messages are formatted in IoToad check: IoToad MQTT design.

api parses the REST message and relays them to other modules through MQTT messages.

The MQTT messages have two fields data and response_topic. In the data field is sent the payload and the response_topic is a random MQTT topic where api module listens for the message reply.

A MQTT message is sent for every topic in the subtopics.

Example 1: with ‘subtopics’

If the PUT data is…

{
    "subtopics": [
        "<subtopic:1>",
        "<subtopic:2>"
      ],
      "payload": "<payload>"
}

Will publish two MQTT messages…

1st message

<agent>/<subpath>/<subtopic:1>

{
    "response_topic": "<response-topic:1>",
    "data": "<payload>"
}

2nd message

<agent>/<subpath>/<subtopic:2>

{
    "response_topic": "<response-topic:2>",
    "data": "<payload>"
}

Example 2: without ‘subtopics’

If the PUT data is…

{
    "payload": "<payload>"
}

Will publish a single MQTT message…

<agent>/<subpath>

{
    "response_topic": "<response-topic>",
    "data": "<payload>"
}

Real example

HTTP REST request

PUT api/in/sp_command/

{
    "subtopics": [
        "m1",
        "w.r1.c0"
      ],
      "payload": {"status":"OFF"}
}

MQTT publications

It will publish two times to MQTT.

1st publication

command/sp_command/m1

{
     "response_topic": "responses/api/809bd939baa44f1f87fdd1099ea05a62",
     "data": {"status" : "OFF"}
}

2nd publication

command/sp_command/w.r1.c0

{
     "response_topic": "responses/api/42694cca24614db48ad12f8f89be642b",
     "data": {"status" : "OFF"}
}

api/out

REST

HTTP method: GET

URL: api/in/<agent>/<subpath>?<param:1>=<value:1>&<param:2>=<value:2>

  • <agent> is the module to which you want to send data, for example sp_command/status or sp_command/status/sp_r3c4.

  • <subpath> is the subtopic of mqtt to which it will be published. If you want to publish to several subtopics, <subtopic> will be omitted from the URL and a “subtopics” field will be created in the data sent as described below.

  • <param:n>/<value:n> are the parameters that specify the query.

URL examples

  • api/out/influx_query/sp/power?type=w

  • api/out/influx_query/sp/power?operation=sum&type=w&from=1585217932.2041745

  • api/out/influx_query/sp/power?operation=median&type=w&row=1&from=1585217932.2041745&to=1585300000.2041745

  • api/out/influx_query/sp/status?operation=median&type=g

  • api/out/influx_query/sp/status?operation=sum&id=w.r1.c2

MQTT

In order to understand how MQTT messages are formatted in IoToad check: IoToad MQTT design.

The MQTT messages have two fields data and response_topic. In the data field are sent all the GET parameters as a json, and the response_topic is a random MQTT topic where api module listens for the message reply.

Example

If the GET request is…

api/out/<agent>/<subpath>?<param:1>=<value:1>&<param:2>=<value:2>

Will publish a single MQTT message…

data/<agent>/<subpath>

{
    "response_topic": "<response-topic>"
    "data": {
        "<param:1>": "<value:1>",
        "<param:2>": "<value:2>"
    }
}

Real example

HTTP REST request

GET api/out/influx_query/sp/power?operation=sum&type=w&from=1585217932.2041745

MQTT publication

query/influx_query/sp/power

{
     "response_topic": "responses/api/809bd939baa44f1f87fdd1099ea05a62",
     "data": {
         "operation": "sum",
         "type": "w",
         "from": 1585217932.2041745
     }
}