Versioning

Starting with the Release version 19.08.1, currently scheduled to be released on August 9, 2019, a new Versioning requirement will be introduced to the Bluescape APIs.

You will need to add a version parameter to the API endpoints for them to select what version of the APIs you will use. You will have until October 11, 2019, to include/upgrade your scripts before the old versions are retired from functionality.

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 upcoming Release Version 19.08.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.08.01 Release (scheduled for August 9, 2019)?
A: No, they will continue to work without adding the version parameter to the endpoints until the Release 19.10.1, currently scheduled to be released on October 11, 2019. Starting with the Release 19.10.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.

Q: Do I need to add /v0/ to my working scripts before the 19.08.01 Release?
A: No, do not add or modify anything to your working API endpoints. You do NOT need to add /v0/.

Q: When will the use of versioning on the API endpoints becomes mandatory?
A: Starting with the Release 19.10.1, currently scheduled to be released on October 11, 2019, the use of a version parameter on the API endpoints will become mandatory.

Q: Do I simply add version 1 (/v1/) to my scripts?
A: The introduction of version 1 (/v1/) includes changes in the paths of certain entrypoints. You are encouraged to verify the path of the entrypoints when updating your APIs.

Q: What version should I use for my APIs?
A: Starting with the Release 19.08.1, you are encouraged to add version 1 (/v1/) 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/users/me/workspaces
New format:
https://api.apps.us.bluescape.com/v1/users/me/workspaces

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

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

Versions

Version Path Introduction release Status
1.0 /v1/ 19.08.1 (August 9, 2019) Current
0.0 /v0/ Baseline version Previous version