Skip to main content

Handling Iotnodes

This document contains some examples of some common API calls for handling iotnodes. A more detailed description of every endpoint can be found in the Swagger documentation.

Iotnodes (i.e. entities) can be interacted with in two ways, either through regular Yggio API or through the NGSI v2 API. For more information about the NGSI v2 API, see the NGSI section.

All examples requiring access tokens will be denoted as "Bearer <token>" where <token> should be replaced with your own access token.

Update a iotnode​

In this example we update the description of the device.

curl -sS -X PUT https://staging.yggio.net/api/iotnodes/<device_id> \
-H 'authorization: Bearer <token>' \
-H 'content-type: application/json' \
-d @- <<EOF
{
  "description": "My new description"
}
EOF

Fetching iotnodes with q query filter​

With custom queries (or "q-queries") you can perform powerful device filtering.

In this example we use a q-query to fetch all devices with the contextMap.Place property set to Building1.

GET https://staging.yggio.net.yggio.net/api/iotnodes?q=contextMap.Place:Building1

A detailed guide on q-queries can be found in the Yggio control panel.

Fetching iotnodes with pagination​

A maximum of 2000 iotnodes can be fetched on one request. Pagination is done with the cursor pagination method.

To use pagination, cursorId, cursorDirection and orderBy needs to be supplied.

Full pagination is only supported for _id, name and reportedAt.

To use pagination with other properties, you need to also filter on the property you are ordering by.

To get the next page you need to include orderBy, cursorDirection=next and set cursorId to the orderBy property of the last iotnode in the previous response.

Example: orderBy=name cursorDirection=next cursorId=NameOfLastDevice

To get the previous page you need to include orderBy, cursorDirection=prev and set cursorId to the orderBy property of the first iotnode in the previous response.

Example: orderBy=name cursorDirection=prev cursorId=NameOfFirstDevice

A practical example of how to fetch ALL iotnodes with pagination​

const TOKEN = 'x'; // Auth token
const SERVER_URL = 'https://example.yggio.net';

const BASE_URL = `${SERVER_URL}/api/iotnodes?limit=1000&orderBy=_id`;

const REQUEST_OPTIONS = {
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    accept: 'application/json',
  }
};

let cursorId;
let allIotnodes = [];

while (true) {

  let URL = BASE_URL;

  if (cursorId) {
    URL = `${BASE_URL}&cursorDirection=next&cursorId=${cursorId}`;
  }

  const response = await fetch(URL, REQUEST_OPTIONS);

  const iotnodes = await response.json();

  allIotnodes = allIotnodes.concat(iotnodes);

  if (iotnodes.length === 0) {
    break;
  }

  cursorId = iotnodes[iotnodes.length - 1]._id;

}

// allIotnodes now contains all iotnodes