Versioning

With the release version 19.11.1, released on November 22, 2019, a new API version has been introduced.

You will need to update the version parameter pointing to the API endpoints from /v1/ to /v2/ in order to ensure that you are using the most current API version.

NOTICE

The support for API version /v0/ is now discontinued. All API calls to an endpoint must now include a (/v1/ or /v2/) version parameter.

Versions

Version Path Introduction release Status
2.0 /v2/ 19.11.1 (November 22, 2019) Current
1.0 /v1/ 19.08.1 (August 9, 2019) Previous version
0.0 /v0/ Product Baseline Discountinued

FAQ

Q: Why is Bluescape adding versioning to the APIs?
A: Bluescape is adopting the use of Semantic Versioning 2.0.0 for our APIs, see https://semver.org/ for full details. Previously there were no guarantees which APIs would break in any release -- if your code stopped working because we changed our APIs, you had to call us to confirm. With the adoption of semantic versioning, there will be clear communication about any incompatible changes, which can only happen in a major release. Major releases will be clearly announced, like the release Version 19.11.1. Within a major version, we commit to introducing only backwards-compatible changes. If you are using Bluescape APIs, you can now be confident that a minor or patch release to our APIs will not invalidate your hard work.

Q: Will my current scripts stop working after the 19.11.1 Release (released on November 22, 2019)?
A: Starting with the Release 19.11.1, the use of a version parameter on the API endpoints will become mandatory. Any API calls not using a version parameter will stop working, however scripts using endpoint /v1/ will continue to work.

Q: Do I need to add /v2/ to my working scripts after the 19.11.1 Release?
A: Any scripts using the /v1/ endpoint will continue to work, although we recommend updating these to the most current supported endpoint /v2/. Before updating to /v2/, check all scripts that are potentially impacted by the migration of id to uid fields in API responses. See more details in the id to uid migration page.

Q: What version should I use for my APIs?
A: Starting with the Release 19.11.1, you are encouraged to add version 2 (/v2/) to your currently working scripts. For example, to view all the workspaces that a user can access, make the following change:
Current format:

https://api.apps.us.bluescape.com/v1/users/me/workspaces
New format:
https://api.apps.us.bluescape.com/v2/users/me/workspaces

To add a new canvas to a workspace, make the following change:
Current Format:
https://api.apps.us.bluescape.com/v1/workspaces/<workspace_id>/canvas
New format (note the new addition of elements in the path):
https://api.apps.us.bluescape.com/v2/workspaces/<workspace_UID>/elements/canvas

Still have questions? If you have any questions or comments, please contact us at Bluescape support