What is new in v3?
This page covers the new features in v3, as a comparison with v2.
One new inclusion in v3 are the new GraphQL APIs.
Regarding the REST APIs, the main differences can be grouped in 3 sections:
Changes in REST API verbs
In v3, to modify a property of an object that is already created (its position, color, text, etc.), the REST API verb to use is PATCH.
In v2:
Use the REST API verb: PUT
Specify the properties to change in the request body of the PUT call.
In v3:
Use the REST API verb: PATCH
Specify the properties to change in the request body of the PATCH call.
Note: The following v3 REST APIs that still use the PUT verb to make a change:
- Progress Asset Upload to processing:
PUT /v3/workspaces/{workspace}/assets/uploads/{id}
- Update the Member’s Role:
PUT /v3/organizations/{organizationId}/members/{memberId}/role
- Update Avatar:
PUT /v3/users/me/avatar
- Favourite a workspace:
PUT /v3/users/me/favorites/workspaces/{workspaceId}
Changes in Request and Response Body
In v3, fields containing the unique IDs for each object are no longer using the “uid” name or suffix, they are now called “id” or use the “id” suffix. See the example of the response body for getting a workspace.
v2 example:
{
"workspace": {
"uid": "vfg6CZFHqWqsVjyZNhmH",
"name": "Vladimir - project, notes, etc.",
...
"organization": {
"name": "Bluescape",
"uid": "wOETxsWt3SAmuyUQbbLy",
"default_public_workspace_role_uid":
"VJKO1MCvXQLfhMB6bzde"
},
"favorite": false,
"users_count": 12,
"workspace_owner": {
"first_name": "Vladimir",
...
"uid": "DbfcGpN-U30XIjjy0yjX"
},
"workspace_role": {
"name": "Owner",
...
"uid": "HLBI9sd-yyHWupboR7MH"
},
"organization_uid": "wOETxsWt3SAmuyUQbbLy",
"default_role_uid": "VJKO1MCvXQLfhMB6bzde"
}
}
v3 example
{
"id": "j5FIqcSmCpkJjXnWb8qk",
"name": "Team Project",
"description": "",
"isPublic": true,
"defaultRoleId": "gQ2DA6mMC4Op-_EHuR6S",
"organizationId": "5JIGySFmJpfen3Jnozqx",
"ownerId": "qIN-MJbWD1fGByxm-qw4",
"updatedAt": "2020-12-04T00:54:31.000Z"
}
In v3, elements are no longer grouped by their type when running a GET API to get the list of elements from the workspace.
In v2:
The response body delivers the elements of the workspace grouped by type:
- all text objects within this array:
"text": [...]
- all strokes within this array:
"strokes": [...]
- all images within this array:
"images": [...]
List of Types in v3: text, images, browsers, documents, grids, notes, strokes, videos, canvas.
In v3:
Elements are not grouped by type.
- the response body contains all the elements within this array:
"data": [...]
- and each element contains its type definition, specified by the “type” key. e.g.:
-
"type": "Text" -
"type": "Canvas"
-
An example of this in v3:
{
"data": [
{
"id": "5fc7f508e2db9d003ee5ee4c",
"zIndex": 5,
...
"type": "Text",
"text": "Text - test 1",
...
},
{
"id": "60249bc63fe6b011cc752a4d",
"zIndex": 10,
...
"type": "Canvas",
"name": "Top Canvas",
...
}
]
}
List of Types in v3: Text, Note, Image, Document, Grid, Browser, Video, Stroke, Shape, Line, Canvas.
In v3 there is a new way to specify the position of objects in the workspace.
In v2 use:
{
"text": "Hello there!",
...
"x": 100,
"y": 200,
...
}
In v3 the position of an object is specified within the transform key:
{
"type": "Text",
"text": "Hello there!",
...
"transform" : {
"x": 100,
"y": 200
}
...
}
In v3 there is a new way to specify the dimensions (height and width) of an element, except for elements of the Image, Document, or Video type.
In v2:
All the elements specify the width and height properties this way:
{
"text": "Hello there!",
...
"width": 300,
"height": 200,
...
}
In v3:
The dimensions of an element are specified within the style key (except for elements of the Image, Document or Video type):
{
"type": "Text",
"text": "Hello there!",
...
"style": {
"width": 300,
"height": 200,
...
},
}
...
}
For the elements of the Image, Document, or Video type, the width and height properties are specified as in v2:
{
"type": "Image",
...
"width": 300,
"height": 200,
...
}
In v3 there is a new way to specify the color schema for elements.
In v2:
Color is specified in the following manner, for a Text object:
{
"text": "Hello, new text!",
...
"fontColor" : "#ffffff",
"backgroundColor": "Red"
}
In v3:
Color scheme is defined using RGBA color model. For more information on RGBA visit RGBA Color Model.
The color is defined by:
- R: how much red
- G: how much green
- B: how much blue
- A: alpha channel, how opaque the color is (0: transparent, 1: solid color)
The color properties of an object are specified within the style key, also for a text object:
{
"type": "Text",
"text": "Hello there!",
...
"style": {
...
"color": {
"r": 255,
"g": 255,
"b": 255,
"a": 1
},
"backgroundColor": {
"r": 255,
"g": 0,
"b": 0,
"a": 1
},
}
...
}
Different to v2, in the currently available version of v3, you cannot create elements associated directly into a Canvas, but you can list all the elements within a Canvas.
In v2 you can create elements directly into a Canvas. These elements are displayed in the Canvas, using the top-left corner as the (0,0) point of reference for their coordinates. If no set of (x,y) coordinates are specified, then they will be placed in the top-left corner of the Canvas.
Example: Create Text in Canvas
/v2/workspaces/{workspace_id}/elements/canvas/{canvas_id}/text
To list the elements inside a Canvas, in v2 you can use:
GET /v2/workspaces/{workspace_id}/elements/canvas/{canvas_id}/elements
In the currently available version of v3, there is no method to create an element into a Canvas, even if you provide a parameter such as the one below to a POST call:
?canvas={canvasID}
But there is a way to list the elements inside a Canvas. In v3 you can use:
GET /v3/workspaces/{workspace_id}/elements?canvas={canvas_id}
Here is a summary example of how to specify the style properties of an object: position, height/width, color, and background color. This is applied to a new Text element.
In v2:
{
"text": "Hello there!",
...
"x": 1000,
"y": 2000,
"width": 300,
"height": 200,
"fontColor": "blue",
"backgroundColor": "white",
...
}
In v3:
The dimensions of an object are specified within the style key:
{
"type": "Text",
"text": "Hello there!",
...
"transform" : {
"x": 1000,
"y": 2000
},
"style": {
"width": 600,
"height": 400,
...
"color": {
"r": 0,
"g": 0,
"b": 255,
"a": 1
},
"backgroundColor": {
"r": 255,
"g": 255,
"b": 255,
"a": 1
},
}
...
}
Changes in the path of the REST APIs
How to get the list of all objects of an object type in the workspace
NOTE: The object types are different in v2 and V3, see the difference sin casing and names
In v2:
GET /v2/workspaces/{workspace_id}/elements/{object_type}
List of Types in V2: text, images, browsers, documents, grids, notes, strokes, videos, canvas.
In v3:
GET /v3/workspaces/{workspaceId}/elements**?type={object_type}**
List of Types in V3: Text, Note, Image, Document, Grid, Browser, Video, Stroke, Shape, Line, Canvas, Selection, Window.
How to get the content of a Canvas
In v2:
GET /v2/workspaces/{workspace_uid}/elements/canvas/{canvas_uid}
In v3:
GET /v3/workspaces/{workspaceId}/elements?canvas={canvasID}
How to get the content of a Canvas, for a specific object type
In v2:
GET /v2/workspaces/{workspace_uid}/elements/canvas/{canvas_uid}/{object_type}
In v3:
GET /v3/workspaces/{workspaceId}/elements?canvas={canvasID}&type={object_type}
How to create an element, e.g. a Text element
In v2:
POST /v2/workspaces/{workspace_id}/elements/text
In v3:
POST /v3/workspaces/{workspaceId}/elements
Ensure that you provide the type in the request body:
{
"type": "Text"
...
}
How to create an element in a canvas, e.g. a Browser element
In v2:
POST /v2/workspaces/{workspace_id}/elements/canvas/{canvas_id}/browsers
In v3:
POST /v3/workspaces/{workspaceId}/elements?canvas={canvasId}
Ensure that you provide the type in the request body:
{
"type": "Browser"
...
}
How to get a my user’s list of organizations
In v2:
This data is displayed in the response body of
GET /v2/users/me
or
GET /v2/users/me/organizations
In v3:
This data is only available as the response of
GET /v3/users/me/organizations
Where to Next?
Not what you were looking for? Reply below or Search the community and discover more Bluescape.