Difficulty: expert
Content
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.
Note
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.
Note
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:
Code 200 - Response body empty ([])
For example if the From date lies in the future, response body will be empty
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).
Info
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 https://en.wikipedia.org/wiki/Percent-encoding for more details on proper encoding of special characters.