Introduction to Push

In communication through Push, the device proactively searches for commands to be executed through HTTP requests periodically sent to the external server it is configured for.

When there is no command to be executed by the device, the server must send an empty response. Otherwise, the server must answer the command to be performed and the corresponding parameters.

After the device executes the command read from the server, it sends a new request containing the response of the operation performed. An empty response is expected to this request, which closes the Push transaction. After each command is executed, the device will make a new /push request, allowing the execution of multiple commands in sequence.

To use Push you need to set some configuration parameters described in push_server.

Endpoints

An endpoint of a web server is the URL by which one of its services can be accessed by a client application. Therefore, endpoints are interfaces between the API and the application.

The final URL to which the events will be sent by the device will be:

hostname:port/endpoint

Endpoints examples:

• http://myserver.com/push
• 192.168.110.200:80/push

Event: command searches on the server

The device makes periodic requests to the server to check for any push from the server.

The HTTP method used is the GET and all parameters are sent through the query string.

GET /push

Parameters

• deviceId (int 64): Device's ID which is making the request.

Response

Command's return to the device

Return message from the server to the device after a push attempt event.

Response of the analysis of the push attempt.

Field	Type	Description
verb	string	Specifies the HTTP method (GET or POST) that will be used to execute the command on the device. The default value is POST. (Optional)
endpoint	string	Specifies the command that will be executed on the equipment. See the API sections for possible commands. (Optional)
body	string	Sends the command parameters to be executed at the device. See the command documentation for the required parameters. (Optional)
contentType	string	Specifies the type of data that will be sent in the body of the request. The default value is application/JSON. If the contentType is application/octet-stream, the body content must be sent in a single string representing this content in base64 format. (Optional)
queryString	string	Sends the query string parameters needed to execute the command. (Optional)

Response example of a /push request

{
   verb: "POST",
   endpoint: "load_objects",
   body: { object: "users" },
   contentType: "application/json"
}

*An empty response means that there is no push to be performed.

Event: command result

Sends the result of the push execution to the server. This request contains the result of the command executed on the device.

The HTTP method used is the POST.

POST /result

Parameters

• deviceId (int): The ID of the device which is making the request. (This parameter is sent in the query string)
• response (string): Contains the response given by the API with the push execution. See the command documentation for more information about the response format. Note that this parameter is present only if no error occurs during the operation.
• error (string): Specifies the error that occurred during the push execution. Note that this parameter only exists if an error occurs.

Request example

Request with the result of listing users.

{
    "response": {
        "users": [
            {
                "id":1,
                "registration": "Test",
                "name": "Walter White",
                "password": "Heisenberg",
                "salt": "",
                "expires": 0,
                "user_type_id": 0,
                "begin_time": 0,
                "end_time": 0
            }
        ]
    }
}

Response example:

The response to this request is empty.