Introduction

OpenGate initiates communication with the device, requesting the execution of a specific operation. Upon receiving this request, the device can respond in either a synchronous or asynchronous manner, utilising the HTTP protocol.

Devices can expose this endpoint so that OpenGate can request operation executions on them.

Synchronous

The entirety of the operation is driven by a single HTTP request and response: the device executes the operation and returns the result in the response body of the same exchange.

sequenceDiagram
    participant OG as OG Connector
    participant Dev as Device

    rect rgb(240, 246, 255)
    Note over OG,Dev: Platform generated command
    OG->>+Dev: COMMAND (HTTP REQUEST -> POST)<br>Command Info (JSON)
    Note over Dev: executes the operation
    Dev-->>-OG: RESPONSE (HTTP RESPONSE) 201 Ok<br>Response Info (JSON)
    end

Asynchronous

In this instance, OpenGate transmits the operation to the device via an HTTP request, and the device responds with an acknowledgement through the utilisation of an HTTP response. Subsequently, OpenGate is capable of receiving one or multiple HTTP requests transmitted by the device. These HTTP requests can be employed by the device to convey the subsequent steps that the operation necessitates.

For further information on the endpoints exposed by OpenGate for the management of asynchronous operation communications, please refer to the section on operations driven by device.

Simple response

The device transmits a sole response message in order to respond to the request.

sequenceDiagram
    participant OG as OG Connector
    participant Dev as Device

    rect rgb(240, 246, 255)
    Note over OG,Dev: Platform generated command
    OG->>+Dev: COMMAND (HTTP REQUEST -> POST)<br>Command Info (JSON)
    Dev-->>-OG: COMMAND ACK (HTTP RESPONSE) 201 Ok
    end

    Note over Dev: executes the operation

    rect rgb(240, 246, 255)
    Note over OG,Dev: Device generated response
    Dev->>+OG: RESPONSE (HTTP REQUEST -> POST)<br>Response Info (JSON)
    OG-->>-Dev: RESPONSE ACK (HTTP RESPONSE) 201 Ok
    end

Multiple responses

The device can transmit a number of partial responses and a final response at the conclusion of the sequence.

Partial responses carry no resultCode: that is what marks them as intermediate. The final response includes it, closing the operation.

sequenceDiagram
    participant OG as OG Connector
    participant Dev as Device

    rect rgb(240, 246, 255)
    Note over OG,Dev: Platform generated command
    OG->>+Dev: COMMAND (HTTP REQUEST -> POST)<br>Command Info (JSON)
    Dev-->>-OG: COMMAND ACK (HTTP RESPONSE) 201 Ok
    end

    rect rgb(240, 246, 255)
    Note over OG,Dev: Device generated partial response
    Dev->>+OG: PARTIAL RESPONSE (HTTP REQUEST -> POST)<br>Response Info (without resultCode)
    OG-->>-Dev: RESPONSE ACK (HTTP RESPONSE) 201 Ok
    end

    Note over OG,Dev: one exchange per partial response

    rect rgb(240, 246, 255)
    Note over OG,Dev: Device final response
    Dev->>+OG: RESPONSE (HTTP REQUEST -> POST)<br>Response Info (JSON)
    OG-->>-Dev: RESPONSE ACK (HTTP RESPONSE) 201 Ok
    end

Operation structure

Simple request/response

The operation is comprised of a single request and a single response, which together constitute its entirety. There are no intermediate steps. It can be executed in either a synchronous or asynchronous manner, with the latter resulting in a simple response.

Multi-step response

In order to facilitate the monitoring of the operation, it is necessary to define a list of steps. The device is capable of providing information regarding these steps in a single response or in a series of partial responses until the final step is reached. The device can respond using either a synchronous or an asynchronous (simple or multiple responses) flow strategy.

Response structure

In regard to the JSON format, there is no distinction between synchronous and asynchronous responses.

  • Synchronous: The device incorporates the JSON payload into the HTTP response.
  • Asynchronous: The device incorporates the JSON payload into a new HTTP POST, which is initiated by the device itself.

API specification

Device HTTP ports

  • Unsecure (deprecated): 1123
  • Secure: 11235

Usage example

In this flow the device acts as the HTTP server: OpenGate sends the operation request to the endpoint exposed by the device. Request body sent by OpenGate:

{
  "operation": {
    "request": {
      "timestamp": 1614169437035,
      "name": "EQUIPMENT_DIAGNOSTIC",
      "parameters": {},
      "id": "27dfeb18-e13f-45eb-abcc-b8b215c30599"
    }
  }
}

Synchronous response body returned by the device with HTTP 201:

{
  "operation": {
    "response": {
      "id": "e05e4354-ffe0-4cfa-8030-f6b9500b64ab",
      "timestamp": 1432454278000,
      "deviceId": "device_1",
      "name": "EQUIPMENT_DIAGNOSTIC",
      "resultCode": "SUCCESS",
      "resultDescription": "No Error",
      "steps": [
        {
          "name": "MOTHER_BOARD",
          "timestamp": 1432454278000,
          "result": "SUCCESSFUL",
          "description": "Motherboard is Ok"
        }
      ]
    }
  }
}