Rest API: Testing & Troubleshooting

Avatar
Laura CARBO

Difficulty: expert

Content

Learning Objectives

After reading this article, you’ll be able to:

  • test Workplace APIs

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

  1. Select "Try it out",
  2. then "Execute",
  3. 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.

image-20240524-135529.png

Example 2. Get the current sensor data for a location

  1. Select "Try it out",
  2. Add the mandatory location ID
  3. then "Execute",
  4. 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.

image-20240524-135801.png

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.

Info

Location ID is available in the Workplace back-end https://studio.cobundu.com URL for each selected location.

For example the Location ID for floor “2nd floor” in Spacewell Antwerp offices is “910000000004545”

image-20221004-082232.png

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)
image-20221004-083233.png

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

image-20221004-081231.png

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.

Note

For every auth-based API method, make sure to choose the latest version (status September 2024: v2 is the latest, so refer to https://login.cobundu.com/rest/v2/docs)

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

  1. Using API to get session token

    1. Go to https://login.cobundu.com/rest/v2/docs (user needs either Admin or Developer role)

      1. Select "auth" > /auth/ssosettings/{loginId} (return sso settings for the user)

      2. Provide user name
      3.  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)
        image-20240910-073257.png

    2. 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)

      1. Select "auth" > /auth/login (authenticate user)

      2. Specify username + password that will be used to access live data
      3. Change the login parameter "rememberme": true
      4. The rest field can be removed. Example (try not to leave a comma in the end of the password line): image-20240910-073146.png

      5.  Response body will provide accessToken
        image-20240910-073431.png

      6. Access token is ready to be used
  2. Prepare Web kiosk URL

    1. Go to http://go.cobundu.com (user needs either Admin or Developer role) > Kiosk Mode

    2. Select the relevant floor > open web kiosk
    3. Web Kiosk URL will have format https://go.cobundu.com/kiosk/MEETING%7C1d18e8b0-48a7-464c-8813-66608b474d6d
    4. 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
      image-20240910-073939.png

    5. 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| ...
    6. Add suffix "?jwt=" and copy/paste accessToken at the end of the URL
    7. image-20221004-080213.png
  3. 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.

    1. After the token is obtained, there are 10 minutes to pass it in the URL to open the floor plan.

    2. 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

image-20241209-150441.png

Articles in this section