Instance Mapping API
Instance Mapping API
The API allows mapping the following variables within the environment:
Client ID / Client Description / Facility ID / Facility Description / Device ID / Device Description / Address / Endpoint ID / Endpoint Description.
Note:
The API has a limitation of a maximum of 500 records (if not specified, it defaults to 100) to avoid impacting the environment's performance. Therefore, it must be executed multiple times to map the entire instance.
The user can execute the service as follows:
GET/api/v2/instance/mapping/{SequenceNumber}?accessToken={accessToken}
Parameters
- SequenceNumber = Sequence number. Starts at 0.
- accessToken = Global Administrator Access Token
- MaxFetchItems = Maximum number of elements to retrieve (Optional. Default 100, Maximum 500)
Notes:
The number of elements obtained may be larger since the API will return the owner entities of each entity, in the order (Client, Facility, Device, Enpoint) and, because of this, elements may repeat between executions.
Theory of operation
To obtain a detailed list of the instance (Endpoint, Device, Facility, Client) incrementally, the SequenceNumber field is used. This field is monotonically ascending, meaning that when changes occur in any entity, its SequenceNumber field will change to a value higher than any other entity. This allows retrieving data based on the SequenceNumber in small batches until no more data is obtained, and then continuing periodically to get updates. When the result of this API is an empty list, it means that there are currently no updates.
Typically, an application consuming this API uses the following flow:
- The application starts using a stored SequenceNumber (typically in non-volatile storage). On the first execution, this value is 0.
- The application executes the API using (stored SequenceNumber 0).
- The application receives a list of entities, and the last SequenceNumber.
- If the received list is empty, the application waits a few seconds and returns to step 2.
- If the received list is not empty, the application stores the received SequenceNumber.
- The application immediately returns to step 2.
- When a new entity is created, or an existing one is modified, its SequenceNumber will immediately change to a value higher than the last received, so its information will be received immediately in the next execution.
Request:
GET:/api/v2/instance/mapping/{SequenceNumber}?accessToken={accessToken}&maxCount={MaxFetchItems}
Parameters
| It is mandatory to include the following parameters "SequenceNumber" and "accessToken". The "AccessToken" must be generated by a global administrator and the "SequenceNumber" will vary with each execution. |
|---|
Empty entity response: when it returns empty after traversing all entities within an environment, the user can make the query again using 0 "SequenceNumber".
Note:
Important definitions.
The complete tree will not be obtained until the entire instance has been mapped.
It will not be displayed sorted but it will be hierarchical.
Where there is no endpoint, nothing will be returned. Only the complete branch will be returned.
Response: The response contains the list of variables, as shown in this example:
