API Changes

Warning

In version 43, we launched a new version of our API.

Version 1 of the API will be removed on 1st June 2021.

This document covers the following topics:

Why are we making this change?

There are several reasons:

CSV format is no longer supported in the API

  • It has been 12 months since we deprecated the old CSV file formats and we now need anyone still using them to move to the new XML format.
  • If you still require support for CSV files, you should use our new console app (see Console App).

Schema Improvements

  • We are improving the employee schema but we must maintain backwards compatibility within the same version (i.e. API v1).
  • For these improvements, it was not possible so we have to release a new version of the API.

Security Improvements

  • During a security audit we discovered some clients who were calling the API from a browser. For example, they embedded some Javascript in their intranet page (e.g. sharepoint) which runs when the user visits it (e.g. it retrieves the data and displays it). This means that the API key is visible in the source of the page (e.g. if any user viewed the source, they could see it) and they could use it to access the API themselves. This in itself was not a problem as we created read only keys (for this exact purpose), however, most of these clients did not realise that is what they should do (or accidentally chose the wrong type) and were using keys which had full access!
  • We decided the best way to prevent this from happening in the future was to separate the wall data from the rest of the API as that was the only endpoint that could be used in a client side script.
  • When we launched Workstars TV, we added the ability to retrieve the JSON data instead of displaying it. This makes it a lot more secure as the Workstars TV URL’s can only view the wall data and cannot access the API. The endpoint for the wall entries in API v2 have been removed.

What do I have to do?

This depends on how you are using the existing API:

I am using the API to upload employees (using XML) - all have email addresses

IMPACT: LOW

In this case:

  • update the URL to reference “v2” of the API (see REST API v2)
  • if you are using the SDK, update it to v3.x.x (see .NET SDK v3.x.x)

This is as simple as changing the version in the URL to “v2” or updating to the latest .NET SDK version in the nuget package manager.

I am using the API to upload employees (using CSV)

IMPACT: HIGH

In this case:

API v2 doesnt supports CSV files. You should either use the XML format or install the console app. The console app will take a CSV file, convert it to the appropriate XML format and upload it using the latest API.

I am using the API to upload employees (using XML) - some don’t have email addresses

IMPACT: HIGH

In this case:

Currently the employee XML files can have very different schemas, depending on whether you are providing emails for everyone or just for some employees. To make the process more consistent, we are making the schemas nearly identical. The only difference is that if the employee has an email, you provide the <email> element and if they do not have an email, you just omit the <email> element.

I am using the API to retrieve the wall entries (e.g. to display them on an intranet, etc.)

IMPACT: HIGH

In this case, you need to setup Workstars TV and use the JSON response (see Workstars TV) instead of the API.