# Operation execution

# Driven by platform

OpenGate initates the communication with the device asking for an operation execution. Once requested, the device can respond on a synchronous or asynchronous way using the HTTP protocol.

# Synchronous

The request/response is embedded in a single HTTP dialog. A single HTTP connection is used.

Figure 3. Synchronous Operation Strategy

# Asynchronous

The request/response is embedded in different HTTP dialogues. Two or more HTTPs connections can be used to communicate the request and to communicate the response or responses.

# Simple response

Only a final response message is sent by the device to answer the request.

Figure 4. Asynchronous Operation Strategy - Simple Response

# Multiple responses

Multiple partial responses can be sent by the device and a final response at the end of the sequence.

Figure 5. Asynchronous Operation Strategy - Multiple Responses

# Operation structure

# Simple request/response

The operation has only a request and a response to finish it. There is no intermediate steps. It can be used synchronously or asynchronously (simple response).

# Multistep response

The Operation requires a list of steps to track the operation. This steps can arrive all together in the final response or gradually in partial responses until finishing with the Final response. It can be used Synchronous or Asynchronous (simple or multiple response) flow strategy.

# Response structure

There is no difference between synchronous and asynchronous responses regarding to the JSON format.

  • Synchronous: The JSON is embedded in the HTTP response.
  • Asynchronous: The file is embedded in a new HTTP POST initiated in the device.

# URIs

Attending to the flow strategies described above south operations API can be summarized:

  • It is used HTTP request/response mechanism with an embedded JSON file to both flow directions:
    • Platform - Device: Synchronous/Asynchronous Operation Request
    • Device - Platform:
    • Operation Response
    • On demand Request
  • Both platform and device must to implement a HTTP web service publishing a URI as defined in the next table:
Side URI Port
Device /v80/devices/{device.id}/operation/request 1123 / 11235 (secure mode)
Platform /south/v80/devices/{device.id}/operation/response 443 (secure HTTP)

# Driven by device

The typical use case is when the remote device wakes up after a long sleep period and ask for its pending operation requests stored for it into OpenGate.

# Request pending operations

Remote devices can request OpenGate for pending operations.

Side URI Port
Platform /south/v80/devices/{device.id}/operation/response 443 (secure HTTP)
Platform /south/v80/devices/{device.id}/operation/pending 443 (secure HTTP)

Ondemand Operation Request

# Security

It's strongly recommended to use the encrypted communication channel using HTTPs (default 443 TCP port).

Besides encryption, you can also take into account that OpenGate implements two authorization mechanisms:

  1. The inclusion of the X-ApiKey HTTP header with the API key of a valid user into the request.
  2. Mutual authentication based on HTTPs PKI infrastructure. The certifacte can be set to an entire organization or per channel.