Versioning

With the release version 20.04.1 - coming April 10, 2020 - API endpoint /v1/ will be discontinued.

You will need to update the version parameter pointing to the API endpoints from /v1/ to /v2/.

NOTICE

The support for API version /v1/ will be discontinued on April 10, 2020. All API calls must now include the /v2/ version parameter. You must also upgrade your scripts to make use of the newly introduced UID where applicable. See more details in the id to uid migration page.

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) Discontinuation Scheduled April 10
0.0 /v0/ Product Baseline Discontinued

FAQ


Q: Will my current scripts stop working after the 20.04.1 Release (released on April 10, 2020)?
A: Any scripts using the /v1/ endpoint will no longer work. You will need to update the version parameter pointing to the API endpoints from /v1/ to /v2/.

Q: What's New in V2?
A: With the /v2/ endpoint, scripts previously using the id field will need to be replaced with the uid field. Before updating to /v2/, check all scripts that are potentially impacted by the migration of id to uid fields in API bodies and responses. See more details in the id to uid migration page.

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

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

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