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://public.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://public.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