Rest API
- Julie Isebaert
- Stefanie De Mesure
- Taras Mudryi
Difficulty: expert
Learning Objectives
After reading this article, you’ll be able to:
understand what Workplace APIs can do
test Workplace APIs
API stands for Application Programming Interface and allows easy exchange of data and functionality. The Workplace API documentation (Swagger) is available in a separate tab in the GO menu.
How to access Workplace API
Go to https://go.cobundu.com/
Login with your credentials
The menu item “API” only appears for users who have a developer or admin role assigned to them. See Roles and Profiles for more information.
How to use Workplace API
Use a server-side solution
While it’s a good idea to get familiar with Workplace API by accessing your tenant’s GO environment through a browser, it’s not advised to use a browser-based approach to integrate our APIs to get data from Workplace into a third-part-database. API should be used server based.
By making requests from a secure back-end, you:
Bypass the browser’s CORS restrictions.
Maintain tighter control over data handling and authentication.
Significantly reduce potential security risks.
Improve performance and scalability.
As a SaaS provider, we do not allow cross-origin in-browser embedding with third-party domains for security reasons. If the end goal is to fetch the sensor data and insert it into their database, we strongly advise building a server-side solution.
Use numbered API versions to avoid conflicts
To use the APIs in your own projects (eg postman), you might be interested to use the swagger.json-link. As you can see in the above screenshot, "latest" page opens per default, but this is of course subject to change.
Use numbered versions (eg https://go.cobundu.com/rest/v3/docs) to avoid conflicts.
Using a specific version has the advantage of being able to compare API versions in future.
For every API method, make sure to chose the latest version
Status September 2024
GO API: v3 is the latest, so refer to https://go.cobundu.com/rest/v3/docs
auth-based API: v2 is the latest, so refer to https://login.cobundu.com/rest/v2/docs
How to interpret the Server Response
Validate the request parameters in the Workplace API Try It Out GUI. The response in the GUI will confirm correct parameters by providing a 200 code and values.
Still, only a 200 code is not enough. It confirms the parameters are correct, but still there might be an issue:
Use Request URL from "API Try it Out" to validate your result
To confirm that the Request URL reply from "API Try it Out" works, you can just paste it in your browser (this will only work for limited set of methods called: those using GET method).
Make sure you’re logged in to Workplace (i.e. have an active Workplace session open) in the same browser before pasting it in the URL bar in order to see the results.
Postman or any other tool you use should reflect the exact same URL as the Request URL visible in the Workplace API Try It Out response. For example the pipe character should be decoded in a certain way in Postman. Check out Percent-encoding for more details on proper encoding of special characters.
Testing the API: examples
It's possible to try out/test the Workplace API. Depending on the request, you might need to fill in some information first.
Example 1. Get the list of sensor devices
Select "Try it out",
then "Execute",
to get a list of all sensor devices currently linked to this tenant.
As you can see in the example, each sensor channel (eg humidity, temperature and CO2 in a comfort sensor) is delivered separately.
Example 2. Get the current sensor data for a location
Select "Try it out",
Add the mandatory location ID
then "Execute",
to get the current sensor data of all sensors that are linked to that location.
As you can see in the example, 1 comfort sensor is linked to the requested location. Therefore all channel values available for this sensor (temperature and humidity in this case) are delivered, as well as the timestamp for which these values were received.
Below examples mention “location ID”. Selecting a location on https://go.cobundu.com/ will show the Reference, e.g. "Meeting Room 1". But in the Workplace back-end, each location has a unique location ID.
For example the Location ID for floor “2nd floor” in Spacewell Antwerp offices is “910000000004545”
Example 3. Reservations
To retrieve the reservations from your environment, you can use Reservations API > "get a list of bookings".
Modify dates in the search instruction and to get (filtered) reservations, each including the location ID, thus indicating which location was booked.
Enter location IDs in the search filter to get filtered data.
Example 4. Get location information
Selecting a location on https://go.cobundu.com/ will show the Reference, e.g. "Meeting Room 1". But in the Workplace back-end, each location has a unique location ID.
Locations API can help you get that information.
Depending on what is needed:
get a list of locations for this client
request specific location information (for example information on a set of workplaces): "get location tree" (filter top-level results = workplace)
Example 5. Floor plan
To get a Workplace floor plan, select API Locations > "get a location's drawing as SVG"
The requested location ID in this case is the floor ID.
"Testing" in swagger will provide a response, but it cannot show the SVG.
Enter the floor location ID in following URL to see the SVG: https://go.eu1.cloud.cobundu.com/rest/v3/locations/floor location ID/drawing/svg
Example 6. Sensor Values
see REST API - GET Sensor Values
Concrete use case: URL to show live floorplan
Imagine you want to push a URL to your kiosk screens to visualize Workplace live floorplan data.
Here, we suggest to provide an access token with a URL, so that anyone with the link can see the live floorplan.
Alternative methods and Frequently Asked Questions about this can be found here: Workplace live floorplan data visualization
The below suggested dedicated method includes web authentication via Rest API. This means a Workplace login + password are needed, and the API will return a JWT token which can be used to access all other API calls. For an authorization-related action we have the COBUNDU Authorization service. It has public Swagger UI (and swagger.json-link) available at https://login.cobundu.com/rest/v2/docs. You may use the API via Swagger UI or Postman, or any other tool of your choice. This example is based on our Swagger UI.
Prerequisites
Web kiosk needs to be configured in Studio
Per floor for which you want to set up visualization, a Workplace user is needed:
Workplace minimum rights/no specific role needed
taking into account reservation features set up for this environment
User name + password
To access API: Workplace user with either Admin or Developer role
Solution
Using API to get session token
Go to https://login.cobundu.com/rest/v2/docs (user needs either Admin or Developer role)
Select "auth" > /auth/ssosettings/{loginId} (return sso settings for the user)
Provide user name
Response body will provide the host name of COBUNDU Auth instance that needs to be used (Workplace IoT Platform is available for EU and US) (could be eg "apiUrl": https://login.eu1.cloud.cobundu.com)
Navigate to the apiUrl + /rest/v2/docs from previous step that is https://login.eu1.cloud.cobundu.com/rest/v2/docs is this example (user needs either Admin or Developer role)
Select "auth" > /auth/login (authenticate user)
Specify username + password that will be used to access live data
Change the login parameter "rememberme": true
The rest field can be removed. Example (try not to leave a comma in the end of the password line):
Response body will provide accessToken
Access token is ready to be used
Prepare Web kiosk URL
Go to http://go.cobundu.com (user needs either Admin or Developer role) > Kiosk Mode
Select the relevant floor > open web kiosk
Web Kiosk URL will have format https://go.cobundu.com/kiosk/MEETING%7C1d18e8b0-48a7-464c-8813-66608b474d6d
In a browser navigate to https://go.cobundu.com/rest/serverinfo or in Postman make a request to https://go.cobundu.com/rest/serverinfo?jwt= and copy/paste accessToken at the end of the URL
The apiUrl contains a correct cloud end-point for you account (EU or US). Replace go.cobundu.com in your Web Kiosk URL with this region apiUrl, you'll obtain eg https://go.eu1.cloud.cobundu.com/kiosk/MEETING| ...
Add suffix "?jwt=" and copy/paste accessToken at the end of the URL
Access this URL (for example in incognito mode), and the web kiosk will open on the chosen floor without asking for identification. A session refresh will run inside the application every 10 minutes.
After the token is obtained, there are 10 minutes to pass it in the URL to open the floor plan.
After the floor plan is loaded, further token renewal will run automatically without session loss or any manual intervention.
Limitations
Web kiosk shows Reservation view (= combined Occupancy and Reservations data (if available))
If browser crashes/computer is unplugged: restart the process to get a new access token
Troubleshooting
Upon error 401 with following response body, try to reload the page using F5
Search