Developer

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

Subject
v2
v3
In V3, when you want to modify a property of an object that is
already created (its position, color, text, etc.), the REST API verb to use is PATCH.
REST API verb: PUT

Specify the properties to change in the request body of the PUT call.
REST API verb: PATCH

Specify the properties to change in the request body of the PATCH call.

Please 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

Subject
v2
v3
In V3, the 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.
{
  "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" } }
{
"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, the elements are not longer grouped by their type when running a GET API to get the list of elements the workspace. v2 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.
v3 does not group the elements 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"
    • etc.

{
  "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 specify the position of objects in the workspace.
In v2:

{
  "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, this 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 (except for elements of the Image, Document or Video type), the dimensions of an element are specified within the style key:

{
  "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, this is the way the color is specified, for example, for a Text object:

{
    "text": "Hello, new text!",
    ...
    "fontColor" : "#ffffff",
    "backgroundColor": "Red"
}

In v3 the color scheme is defined using RGBA color model.
What is RGBA? You can find a detailed explanation here: 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
      },
    }
  ...
}

Differently than as in 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 will be 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 not a method to create an element into a Canvas, not 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}
Let's see a summary example for how to specify the style properties of an object: position, height/width, color, 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


Subject
v2
v3
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
GET /v2/workspaces/{workspace_id}/elements/{object_type}
List of Types in V3: text, images, browsers, documents, grids, notes, strokes, videos, canvas.
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
GET /v2/workspaces/{workspace_uid}/elements/canvas/{canvas_uid}
GET /v3/workspaces/{workspaceId}/elements?canvas={canvasID}
How to get the content of a Canvas, for a specific object type
GET /v2/workspaces/{workspace_uid}/elements/canvas/{canvas_uid}/{object_type}
GET /v3/workspaces/{workspaceId}/elements?canvas={canvasID}&type={object_type}
How to create an element, e.g. a Text element
POST /v2/workspaces/{workspace_id}/elements/text
POST /v3/workspaces/{workspaceId}/elements
Provide the type in the request body:
{
  "type": "Text"
  ...
}
How to create an element in a canvas, e.g. a Browser element
POST /v2/workspaces/{workspace_id}/elements/canvas/{canvas_id}/browsers
POST /v3/workspaces/{workspaceId}/elements?canvas={canvasId}
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