API Reference Versioning
Note: API version v3 is available as GA as part of the 21.10.1 release as of October 08, 2021.
Versions
| Version | Path | Introduction Release | Status |
|---|---|---|---|
| 3.0 | /v3/ | 21.10.1 (October 08, 2021) | Current |
| 2.0 | /v2/ | 19.11.1 (November 22, 2019) | Deprecated |
FAQ
Q: Will my current scripts stop working after the /v3/ is GA on the 21.10.1 Release (released on October 08, 2021)
A: There will be a short grace period after the release where v2 endpoints will still be active to give developers time to migrate their existing scripts to v3 APIs instead. After this period, any scripts using the /v2/ endpoint will no longer work. You will need to update the version parameter pointing to the API endpoints from /v2/ to /v3/.
Q: If I want to upgrade my scripts, could I replace the version number from v2 to v3?
A: No. The new v3 APIs include functionality and response formats that are different from the ones in v2. If you simply change the version to v3, your scripts will break. Please review the examples in the Guides section, where we have examples of how v2 and v3 APIs are used to accomplish the solution for a specific requirement.
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:
https://api.apps.us.bluescape.com/v2/users/me/workspaces
New format:
https://api.apps.us.bluescape.com/v3/users/me/workspaces
To add a new canvas to a workspace, make the following change:
Previous format:
https://api.apps.us.bluescape.com/v2/workspaces/<workspace_UID>/elements/canvas
New format (note the addition of type and updated Id field in the path):
https://api.apps.us.bluescape.com/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 backward-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.
Where to Next?
Not what you were looking for? Reply below or Search the community and discover more Bluescape.