HTTP

The OpenGate Devices API is a REST interface that integrates devices, sensors and machines into the platform. It is the broadest of the south transports: it carries both conversations, in both directions.

The device Over HTTP it can Read
Pushes what it measured POST inventory data (serial number, ICC, MSISDN) and business data as data streams: location, temperature, pressure, consumption Data collection
Receives what to do Accept operation requests from OpenGate, or ask for the ones pending, and report the result Operations

Who calls whom

This is the part worth settling before implementing anything, because it decides which side needs a reachable endpoint:

Flow Who opens the connection The device needs
Data collection The device Outgoing HTTPS only
Operations driven by platform OpenGate To expose an endpoint OpenGate can reach
Operations driven by device The device Outgoing HTTPS only — it polls for pending operations

Devices that sleep, sit behind NAT or have no public address use the device-driven flow, which is the usual case in the field.

Before going to production, read the security tips for operations: HTTPS, X-ApiKey authentication and mutual TLS.

Subsections of HTTP

Data collection

Introduction

API to send raw IoT data to OpenGate.

HTTP data collection

This section shows how to use OpenGate HTTP connector for data collection.

The endpoint allows devices to send raw data to OpenGate.

It can be done by:

  • sending data points with their respective timestamps in different datastreams in a single request
  • sending data points without timestamp in different datastreams in a single request

Note about data streams with special platform processing

Besides the spec info you can find below, it’s worth considering that there are two data streams with special platform processing rules: device.identifier and device.topology.path.

These data streams match fields outside the list of data streams in the collection JSON. Due to this special treatment, these data streams will never be collected from the list of data streams; they will be collected from their fields in the collection JSON.

If you want to collect the data stream device.topology.path you have to fill in the field path of the collection JSON. Or, in case of the device is directly behind a gateway, you can remove the field path and fill in the field device in the collection JSON, OpenGate will collect the data stream device.topology.path with the gateway identifier.

Also, if you want to collect the data stream device.identifier you have to fill in the field device of the collection JSON. If you don’t fill in this field, OpenGate will collect the data stream device.identifier from the device_id (that is, the gateway) in the URI, and all the data in the data streams array will be stored in the gateway collected info.

Usage examples

Send the latest value of each data stream (no timestamp):

curl -X POST 'https://api.opengate.es/south/v80/devices/{device_id}/collect/iot' \
  -H 'X-ApiKey: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "version": "1.0.0",
    "datastreams": [
      { "id": "example", "feed": "feed_1", "datapoints": [{ "value": 333 }] },
      { "id": "key", "feed": "feed_2", "datapoints": [{ "value": "value" }] },
      { "id": "datastream", "datapoints": [{ "value": 1337 }] }
    ]
  }'

Send one data stream with several timestamped data points:

curl -X POST 'https://api.opengate.es/south/v80/devices/{device_id}/collect/iot' \
  -H 'X-ApiKey: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "version": "1.0.0",
    "datastreams": [
      {
        "id": "temperature",
        "feed": "feed_1",
        "datapoints": [
          { "at": 1431602523123, "value": 25 },
          { "at": 1431602523123, "value": 26 }
        ]
      }
    ]
  }'

A valid request returns HTTP 201.

API specification

Operations

Introduction to the Power of OpenGate Operations

OpenGate’s Operations feature is a powerful tool for managing and interacting with remote devices. By leveraging this feature, you can seamlessly integrate and control a wide array of remote devices, enabling unparalleled efficiency and flexibility in your IoT ecosystem.

Key Benefits of OpenGate Operations

  1. Remote Configuration: OpenGate allows you to configure devices remotely, ensuring that settings and updates can be applied without physical access. This feature reduces downtime and operational costs while enhancing device performance and reliability.

  2. Action Requests: With OpenGate, you can issue commands and requests to remote devices in real time, putting you in control and ensuring a responsive system. Whether it’s initiating a firmware update, performing diagnostics, or executing specific tasks, OpenGate ensures that your devices respond promptly and accurately.

  3. Enhanced Integration: The Operations feature seamlessly integrates with your existing systems, respecting and utilizing your current setup. This provides a unified platform for device management, simplifying workflows and enhancing the overall efficiency of your operations.

By utilizing OpenGate’s Operations feature, you can remotely manage, configure, and interact with your devices. This empowers you to maintain optimal performance and achieve greater control over your IoT network. This capability transforms how you manage remote devices, making your operations more agile and responsive to changing needs.

Flexible Operation Control with OpenGate

OpenGate’s Operations feature provides the flexibility to initiate and control operations from both the OpenGate platform and the remote devices themselves. This dual capability ensures that you can maintain optimal control and responsiveness, regardless of your operational needs or the specific scenarios you encounter.

Operation Initiation

  • Platform-Driven Operations: Initiate and manage operations directly from the OpenGate platform, allowing centralized control over device configurations, updates, and actions.
  • Device-Driven Operations: Remote devices can also ask for pending operations, providing a decentralized approach that can be tailored to specific device requirements and conditions.

Additional Resources

For more detailed information on how to utilize these capabilities, please refer to the following links:

These resources offer comprehensive guidance on initiating and managing operations securely, ensuring that your interactions with remote devices are both efficient and safe. By following these guidelines, you can maximize the potential of OpenGate’s Operations feature while maintaining robust security standards.

Subsections of Operations

Operations driven by platform

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"
        }
      ]
    }
  }
}

Operations driven by device

Introduction

The typical use case is when the remote device, having been in a long sleep period, requests the pending operation requests stored in OpenGate.

sequenceDiagram
    participant OG as OG Connector
    participant Dev as Device

    rect rgb(240, 246, 255)
    Note over OG,Dev: Device polls for pending operation
    Dev->>+OG: Retrieve Op. Request (HTTP POST)
    OG-->>-Dev: RESPONSE ACK (HTTP RESPONSE) 201 Ok
    end

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

    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

Usage examples

Ask for pending operations:

curl -X POST 'https://api.opengate.es/south/v80/devices/{device_id}/operation/pending' \
  -H 'X-ApiKey: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "trustedBoot": "ab2a2ed4-780d-11eb-9439-0242ac130002",
    "operation": {
      "request": {
        "deviceId": "6890af9e-781c-11eb-9439-0242ac130002",
        "path": ["gateway_001"]
      }
    }
  }'

Send an asynchronous operation response:

curl -X POST 'https://api.opengate.es/south/v80/devices/{device_id}/operation/response' \
  -H 'X-ApiKey: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "version": "7.0",
    "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"
          }
        ]
      }
    }
  }'

A valid request returns HTTP 201 with a Location header.

API specification

Security tips for operations

Tips to Ensure Security When Using OpenGate Operations

To ensure the security of your operations with OpenGate, follow these recommended practices:

  1. Use Encrypted Communication: Always use secure HTTP (HTTPS) for communication, utilizing the default TCP port 443. Unsecured HTTP communication (default TCP port 80) is deprecated and will soon be unsupported.

  2. Authentication Mechanisms: OpenGate requires authentication for all operations. There are two mechanisms you can use simultaneously for enhanced security:

    • API Key Authentication: Include the X-ApiKey HTTP header with the API key of a valid user in every request.
    • Mutual Authentication: Implement mutual authentication based on secure HTTP PKI infrastructure for an additional layer of security, ensuring the integrity and confidentiality of your communications.

By following these guidelines, you can enhance the security and reliability of your interactions with the OpenGate platform.