The Linksper API is a universal API. It means that no matter the site architecture, no matter the master system integrator, no matter the hardwares installed and integrated, the same queries will be available offering a seamless experience and data structure.

This page will help you to:


VayanData can provide you access to a sandbox. Please contact us: https://vayandata.com/contact-us/


Deep dive in the documentation

Open API

The BOS Linksper Console API documentation is available here: Linksper API

When you have access rights to the Linksper Console administration application on the BOS, you also have access to the API documentation (Open API Format) :


Query collection

In addition to the documentation, a Postman collection is available below. This collection provides examples of requests to interact with a Linksper BOS.

Linksper.postman_collection.json

The collection provides an example for each of the endpoints available in the API.


The collection requires an environment with pre-defined variables to be set-up with Postman accordingly to your Linksper instance. The three required variables are:

  • base-api-url: the local url of Linksper Center instance (localhost if you are on the same machine)
  • username: this is the API username given by the BOS integrator
  • password: Associated password
  • token: will be filled automatically when the authentication succeeds (see below for more info on the auth)


Testing tools

The BOS Linksper has a built-in query testing tool called API Generator. The interface allows you to select phrases to complete based on building data and translate them directly into a query.

These are some of the more common examples. Since the API is much broader and generic, the list of phrases is not exhaustive of the API's capabilities.



Authenticate with Linksper

All communications between a third-party system and the Linksper BOS are done through the Linksper Console API and use HTTPS by default. The security is done by using the TLS protocol in version 1.2

Authentication is required to access the BOS data. This authentication is done by using the JWT technology according to the following scheme.

 


A first POST request must be sent to the endpoint: /oauth/token. The body of the request must contain the login and password in JSON format:


A token is then returned by the BOS in return.


This token must be returned as a header for any request to the BOS using the format

Authorization: Bearer < token>


By default the token is valid for 1 hour.

 


Execute a first request

Once the token is obtained in the previous step, it is possible to trigger its first request:

Example /v1/explore/hierarchies/Structure?depth=3 allows you to browse the geographical tree of the site

 



Understand the API structure

The API is structured under 4 main categories:

  • Explore Discover available data from different perspectives (called "hierarchy"): by a geographic point of view, following the distribution of air through assets...
  • Operate Deep dive on a particular set of data: look for historical data, alarms, apply commands or create bookings
  • Manage Apply administrator modifications (change in the model, parameters...)
  • Troubleshoot: Make sure the system is running properly 


Assets

Assets are a common term for both structural parts of a building like a floor, a space or a zone and physical equipment (AHU, LVS, Sensor...). Good to know:

  • Each asset may produce data which are collected by the BOS and may provide commands (to act on the equipment) which are available through the BOS as well.
  • Each asset has a unique id that can be used across all the queries, a name that can be non human friendly and a display name which is human friendly.
  • Each asset has multiple metadata to provide a context, also called tags. They are standardized and accessible through the additional field "allTags".
  • Each asset has multiple data types described below.

See Linksper asset types for more information


Explore /Hierarchies

A hierarchy is a perspective, a point of view, to describe assets relationships of a building: the geographic structure, the air distribution etc.  Linksper has standardized the hierarchies it offers to third parties, no matter the building, no matter the integrator of the BOS.

The standardized hierarchies are listed here: Linksper assets hierarchies

All these hierarchies are not necessary available depending on the systems acquired by the BOS and the level of tagging selected for the site. Structure is the only one always available.

A query to /v1/explore/hierarchies will list the available hierarchies.


Manage user rights

Creating a new user to access the API

VayanData recommends the creation of at least one user for API access for each service. Multiple users for the same service can be created, especially if they require different data needs.

To create a new user, access the Linksper Console application, the "Secure" menu and the "Users" tab.



Click on the New button located at the bottom of the page, then

  • Enter a name (avoid special characters)
  • Check one or more roles (to create new roles, see the next section on managing access rights)
  • Select JwtAuthenticationScheme
  • Set a password

You can test the authentication directly in Postman by replacing the variables with the values you entered.

 

Access rights management

Linksper has 4 levels of user rights management:

  • Roles are associated with each user
  • Each role has read, write and invocation rights on 2 levels: operator and administrator
  • Each component of the platform (e.g., graph node) is associated with one or more categories.
  • Each property of a component can be defined at operator or administrator level.

The creation of new user rights must be done by a Niagara 4 certified system integrator. This rights management is part of the official TCP Niagara training.


Filtering by Endpoint

The Linksper API is composed of "Endpoints" that allow access to data of various kinds (real-time point readings, historical readings, global commands, etc.). Rights on each endpoint can be defined independently of the user rights. It is thus possible to restrict a user only to reading real time points even though he has user rights to send commands or to read the history of the Niagara viewpoint.

The rights on the endpoints are configured here: Services > WebService > LinksperV1Servlet > endpoints


Scope of access rights

The permissions granted to a user of the API cover all the functions of the BOS:

  • Real time points
  • Historicals
  • The alarms
  • Time programs
  • Data models
  • BOS application data
  • The files