Data Lake

Searching data with OpenGate API

The searching API lets you retrieve provisioned and collected information from the entities registered on the platform.

Using search API, you can manage many situations in which you need to get information, collected by OpenGate, about your remote devices.

Some examples of questions you can answer using the searching API are:

• Where is my lost truck?
• Is my vending machine connected to Internet?
• What is the software version of this smart meter which is rebooting all the time?
• How is the signal strength of this weather station which is off-line most of the time?
• What is the latests operations and its current status launched over different devices
• What is the latests raised alarms associated to my in field resources?
• What is the latest value and history of different sensors and machine parameters?

Searching Features

Where are the FROM and WHERE?

Well, if you’re still thinking in SQL, then you’ll expect to find the word FROM anywhere. Remember, OpenGate exposes its API through a REST interface, so in this case the word FROM is in the URL suffix.

In all response cases, you must POST a valid JSON query and you’ll get an array with the matched specific resources. The query could have next main objects:

• filter: Allows to select the resources that meets with desired information, see Filtering
• limit: Allows paginating the response, see Pagination
• sort: Allows sorting the results, see Sorting
• select: Allows selecting only the parameters you need, see Selecting
• group: Allows grouping the results, see Grouping

{
  "filter": {}, // filter document omitted
  "limit": {}, // limit document omitted
  "sort": {}, // sort document omitted
  "select": {}, // select document omitted
  "group": {} // group document omitted
}

Procedure

Searching in OpenGate platform is pretty easy. You have to send a HTTP request to the API using the POST method, the prefix always is /north/v80/search. Optionally you can attach a JSON file (in the HTTP body) if you need to use paging, sorting, selecting, grouping or filtering features,

You can use the URL above for searching information. So for the impatient, let’s suppose you’re trying to search over your previously provisioned device list, and you’re thinking in a SQL WHERE clause like that:

name like 'device_name' AND (
    serialNumber like '82A75D494B0EBF7A95587285AE78E83F' OR
    serialNumber like '08D83B1864A1F9CFED76DAF426EB04D7')

in this case you must use https://api.opengate.es/north/v80/search/devices URL and POST a JSON payload like that:

{
  "filter": {
    "and": [
      {
        "like": {
          "device.name": "device_name"
        }
      },
      {
        "or": [
          {
            "like": {
              "device.serialNumber": "82A75D494B0EBF7A95587285AE78E83F"
            }
          },
          {
            "like": {
              "device.serialNumber": "08D83B1864A1F9CFED76DAF426EB04D7"
            }
          }
        ]
      }
    ]
  },
  "limit": {
    "start": 26,
    "size": 50
  }
}

Requesting with curl:

curl --request POST \
     --data-binary @search-query.json \
     --header "X-ApiKey: YOUR_API_KEY_HERE" \
     --verbose \
     http://[your_opengate_address]/north/v80/search/devices \
     -H "Content-type: application/json"

Then you’ll receive the device list matching with your query, the response body should be something like that.

{
  "devices": [
    {}, // device body omitted
    {}, // device body omitted
    // a number of other devices
    {}
  ]
}