Developer

Versioning

NOTICE

API version v3 is available as a Beta preview as part of the 21.07.1 release on July 09, 2021. This is a preview only and should not be used for mission critical production integrations until the GA release as it has the potential to change.

Versions

Version Path Introduction release Status
3.0 Beta /v3/ 21.06.1 (June 11, 2021) Beta
2.0 /v2/ 19.11.1 (November 22, 2019) Current

FAQ

Q: What's New in V3?
A: With the /v3/ endpoint, scripts previously using the UID field will need to be replaced (e.g., change the id field in the API endpoint from v2/users/{user_uid} to v3/users/{userId}). Before updating to /v3/, please check all scripts that are potentially impacted by the migration of id fields in API bodies and responses.

For example, to view all the workspaces that a user can access, make the following change:
Previous format:

/v2/users/me/workspaces

New format:

/v3/users/me/workspaces

To add a new canvas to a workspace, make the following change:
Previous format:

/v2/workspaces/<workspace_UID>/elements/canvas

New format (note the addition of type and updated Id field in the path):

/v3/workspaces/<workspaceId>/elements?type=Canvas

Q: Why does Bluescape use versioning with their APIs?
A: Bluescape has adopted 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