REST API comparison guide
This page outlines the changes in certain data objects, and in how those objects relate to others. For a complete map of each v1 endpoint to its v2 counterpart, check out the reference guide.
Authorization
Note: This migration does not apply to Miro's OAuth2.0 endpoint (/v1/oauth). It is not part of the required migration and it will continue to support all versions of the Miro REST API.
Connections
One of the major changes for the v2 REST API is that connections are no longer treated as entities. A board
, a user
, and a team
are all entities, but the relationship between any two of these is determined by the interactions between the objects. Treating the relationship and those interactions as an entity unto itself made the v1 platform unnecessarily complex.
To improve the developer experience for the v2 REST API, we decided to use a more intuitive approach to manage these relationships. Rather than creating and maintaining a special object to represent the connection between two other objects, the objects are now associated through actions, such as inviting a user to a board.
This means that Board User Connection objects and Team User Connection objects no longer exist. Their endpoints have been replaced in v2 with more intuitive API calls, such as Share Board. For a full list of the v2 equivalent for these endpoints, please see the reference guide.
Date and Time
In the v2 REST API, timestamps have changed from the RFC 3339 format (used in the v1 REST API) to the broader ISO 8601 format. These formats are derived from the same basic date-time structure, and both follow the "most-to-least-significant" order, i.e. [YYYY]-[MM]-[DD]T[HH]:[MM]:[SS]
. For nearly every developer, this change should be unnoticeable.
The significant distinction in this format switch is that time zones must be indicated using the trailing Z format, and can no longer take advantage of the -0 shortcut to indicate that there is no preferred time zone.
Boards
Working with Board objects in the v2 Miro REST API should feel familiar, as the board object is largely unchanged compared to the v1 REST API.
Board information
Many of the basic information fields in the board object remain unchanged between v1 and v2. These fields include:
type
continues to beboard
id
continues to be the ID used in the board view linkname
continues to be the name of the boarddescription
continues to be the description of the board, or an empty string if there is no description setviewLink
continues to be the direct link to open the Miro board
picture
is no longer included in the board object, and cannot be updated programmatically. Can be retrieved via the GET Specific Board endpoint in v2.
createdAt
and modifiedAt
are mostly unchanged, with the caveat noted above.
User information
The user information contained in a board object remains the same between v1 and v2. A user object is returned for createdBy
, modifiedBy
, and owner
. User objects are unchanged in v2.
Board User Connection / Board Member
With the larger initiative to remove Connections as objects, the Board User Connection object is now represented by a Board Member object. The objects themselves are intentionally similar and should be familiar to work with. However, the Board User Connection endpoints are not available in v2, and have been replaced with more intuitive endpoints and interactions. To see the recommended replacement endpoints, please refer to the REST API Reference Guide.
A v1 board object also includes a currentUserConnection
value, which is a Board User Connection object. In the v2 REST API, this information is now contained in the currentUserMembership
field, which is a Board Member object.
For a side-by-side comparison of the Board User Connection and Board Member objects, refer to the table below.
Board User Connection object | Board Member object |
---|---|
|
|
|
|
|
|
|
|
Optionally, this object could also contain values for | These values are not included in a Board Member object. |
Team information
The team information contained in a board object remains the same between v1 and v2. A nested team object is returned for team
and continues to contain the same three fields used by the v1 REST API:
type
returnsteam
name
returns a String object of the team nameid
returns the unique identifier for this team
Sharing and Permissions information
In the v2 REST API, sharing and permissions have been expanded to include more configuration options. A board object continues to include a sharingPolicy
field, but the Sharing Policy has been expanded in v2. See the table below for a side-by-side comparison of the sharingPolicy
field across v1 and v2.
|
|
---|---|
| Unchanged in v2 |
| Unchanged in v2 |
Not available in v1 |
|
Not available in v1 |
|
In addition to the expanded Sharing Policy, a v2 board object also contains a Permissions Policy and a Policy object that encompasses both the Sharing Policy and the Permissions Policy.
Widgets / Items
In the Miro REST API v1, the Widget endpoints were polymorphic – meaning that one endpoint was used to interact with all potential widget types. The structure of the call would differ depending on what type of widget you were creating or updating. In the v2 REST API, we have replaced this with an independent endpoint for each type of widget (now called "item") on a Miro board.
The new endpoints should feel familiar to you, as they were designed to mostly follow the structure of the type-specific payloads of the previous widget endpoints. The new endpoints should also feel easier to use, as the expected payload of the call will always be consistent, rather than changing based on the context of the widget type.
This guide will compare the new object structures, but for a full map of v1 endpoint calls to their v2 equivalents, please see the reference guide. Note that there is no longer a universal item create
endpoint, but get
, update
, and delete
are still available at the item-level.
Item
In the v2 REST API, board items are now distinct implementations of Item. When comparing a v1 widget object and a v2 item object, many of the basic information fields in the object remain unchanged between v1 and v2. These fields include:
type
continues to indicate the type of widget/item. This can be any of 10-15 values, includingshape
,frame
, etc.id
continues to be the unique identifier of the widget/itemcreatedAt
andmodifiedAt
continue to be timestamps, with the caveat noted abovecreatedBy
andmodifiedBy
continue to be user objects, which are unchanged between v1 and v2.
The v1 widget object also offered capabilities
and metadata
. Neither of these are currently available for v2 item objects.
In the v2 REST API, all item objects also include the following fields:
- a
data
object that contains properties specific to the item type - a
style
object that contains properties specific to the item type - a
geometry
object that contains awidth
, aheight
, and arotation
for the item - a
position
object that contains thex
andy
coordinates of the center of the item on the board, as well as anorigin
which indicates the point of the item that the x- and y- coordinates refer to.
Cards
For both the v1 card widget and the v2 card item, the type
is card
. The card-specific widget properties are reflected in the card item data
and style
objects, with some minor changes:
title
anddescription
are unchanged between v1 and v2, and both continue to be a String resource for the card header and the card description, respectively.date
has been renamed in v2 todueDate
and continues to be a date-time object, subject to the previously-mentioned format change.- In v1,
assignee
was an object that contained auserId
, while in v2,assigneeId
is a String that directly references that user ID. - In v1, the
style
object included abackgroundColor
property that accepted a String of any valid hex color code. In v2, thestyle
property has been renamed tocardTheme
, but the value of the property continues to be a String of a valid hex color code.
Lines/Connectors
Connectors are available as the equivalent to Lines in the Miro v2 REST API.
While the v1 line widget had a type
of line
, the v2 connector has a type
of connector
. In addition, the line-specific widget properties from v1 have changed in the following ways:
- The v1
startWidget
andendWidget
properties have been renamed in v2 tostartItem
andendItem
. - In v1, the
lineType
property was nested into thestyle
object, but in v2, it has been replaced with a top-levelshape
property.- In v1,
lineType
supported the following values:straight
,orthogonal
,bezier
, andsketch
. - In v2, we simplified the options and renamed several to improve clarity. As a result,
shape
supports the following values:straight
,elbowed
, andcurved
.
- In v1,
- In the
style
object, the following changes have been made:borderColor
is nowstrokeColor
,borderStyle
is nowstrokeStyle
, andborderWidth
is nowstrokeWidth
. These were renamed to improve clarity. The supported values of each property remain unchanged, althoughstrokeWidth
now supports any integer between 1 and 24.lineStartType
andlineEndType
in v1 have been renamed tostartStrokeCap
andendStrokeCap
in v2. This change was made to improve clarity, by noting the difference between the line of the connector, and the decorative cap at the end. In addition to this, the supported values have changed in v2, withnone
being the only value from v1 that is still available in v2. A full list of the v2 supported values can be found in the documentation.
Finally, the v2 REST API provides full CRUD support for connectors, including an endpoint to get all of the connectors in a board, as well as an endpoint to get a specific connector. This is new in v2.
Please see the Work with connectors guide for examples of how to create lines using the current v2 REST API capabilities.
Shapes
For both the v1 shape widget and the v2 shape item, the type
is shape
. The shape-specific widget properties are reflected in the shape item data
and style
objects, with some minor changes:
text
in the v1 shape widget is nowcontent
in the v2 shape itemdata
object, but both accept a String with simple HTML tag support.shapeType
was nested understyle
in the v1 shape widget, but has moved to thedata
object in the v2 shape item, and was renamed toshape
. Both fields accepted 21 possible values, of which the following options have been renamed to improve clarity:rounded_rectangle
is nowround_rectangle
trapeze
is nowtrapezoid
callout
is nowwedge_round_rectangle_callout
predefined_process
is nowflow_chart_predefined_process
barrel
is nowcan
arrow
is nowright_arrow
arrow_left
is nowleft_arrow
arrow_left_right
is nowleft_right_arrow
brace_left
is nowleft_brace
brace_right
is nowright_brace
- The
style
object is largely unchanged between the v1 shape widget and the v2 shape item, save for the following:- Two properties were renamed for improved clarity
backgroundColor
is nowfillColor
backgroundOpacity
is nowfillOpacity
textVerticalAlign
andtextColor
are not currently available in the v2 REST API
- Two properties were renamed for improved clarity
Stickers / Sticky Notes
One major change for sticky notes in v2 is that the item/widget has been renamed. The v1 REST API and Web SDK both referred to sticky notes as "stickers". Since the v1 platform was built, Miro has added support for the more commonly known reaction/emoji stickers. To prevent any confusion, the v2 platform has updated all references to sticky notes to only use the phrase "sticky note".
As a result, the v1 sticky widget had a type
of sticker
, while the v2 sticky note item has a type
of sticky_note
. Beyond that, the sticky-note-specific widget properties are reflected in the data
and style
objects, with the following changes:
text
in the v1 sticker widget is nowcontent
in the v2 sticky note itemdata
object, but both accept a String with simple HTML tag support.- The v1 sticker
style
object provided support for the following fields:backgroundColor
, which accepted a String containing one of 12 approved hex color codes, has been renamed tofillColor
in v2 and now accepts a String containing one of 16 approved color names.fontFamily
andfontSize
are not available in the v2 sticky note item.textAlign
andtextAlignVertical
are unchanged between v1 and v2.
Texts
For both the v1 text widget and the v2 text item, the type
is text
. The text-specific widget properties are reflected in the shape item data
and style
objects, with some minor changes:
text
in the v1 text widget is nowcontent
in the v2 text itemdata
object, but both accept a String with simple HTML tag support.- The v1 text
style
object supported the following fields:backgroundColor
andbackgroundOpacity
, which have been renamed tofillColor
andfillOpacity
, respectively. The possible values are unchanged between v1 and v2.fontFamily
,fontSize
, andtextAlign
, all of which are unchanged between v1 and v2.borderColor
,borderOpacity
,borderWidth
,textColor
, andpadding
, none of which are currently available for the v2 text item.
New items in v2
There are several item types that are available in the v2 REST API, which were not supported in the v1 REST API. These may be interesting to you, so we’ve listed them below.
In addition, Tags are not considered an Item, but are supported in the v2 REST API.
Webhooks
The V2 platform introduces Webhooks to complement the existing capabilities in the V2 REST API. Webhooks were not offered in our v1 capabilities.
You can now subscribe to webhooks for various board and item notifications. See Webhooks for more details.
Teams
Team objects and endpoints have undergone several significant changes between the Miro REST API v1 and v2. Most notably, the teams endpoints are now only available to Enterprise plans, meaning that in order to install applications that use the Enterprise APIs, they must be installed into a team with an Enterprise plan.
For developers working with Enterprise applications, the following information is intended to help you migrate your app from v1 to v2. In addition, you might be interested in checking out the new v2 support for Team Settings, Organizations, and Data Classification.
Team Object
The information contained in a team object has been simplified for the v2 REST API. There are now only three properties for a v2 team object, although they are each unchanged from their v1 counterpart.
type
continues to beteam
name
continues to be a String object of the team nameid
continues to be the unique identifier for this team
The following properties of a v1 team object have changed in v2:
picture
- App pictures, Board pictures, and Team pictures can no longer be set or changed programmatically. However, a team picture, if set, can still be returned in a team object. Similarly, a Board picture can be retrieved via the GET Specific Board endpoint in v2.createdAt
,createdBy
,modifiedAt
, andmodifiedBy
are no longer included in a team object in the v2 REST API.
Team User Connection / Team Member
With the larger initiative to remove Connections as objects, the Team User Connection object is now represented by a Team Member object. The objects themselves are intentionally similar, and should be familiar to work with. However, the Team User Connection endpoints are not available in v2, and have been replaced with more intuitive endpoints and interactions. To see the recommended replacement endpoints, please refer to the REST API Reference Guide.
For a side-by-side comparison of the Team User Connection and Team Member objects, refer to the table below.
Team User Connection object | Team Member object |
---|---|
|
|
|
|
| This field is not included in the Team Member object. |
|
|
| These fields are unchanged in v2 |
| These have been replaced with |
Users
While User objects remain unchanged between the v1 REST API and v2, there are no longer specific endpoints for retrieving those User objects. Instead, user objects can be found nested in the relevant API responses (such as in the createdBy
and modifiedBy
fields).
The v2 user object continues to contain the same three fields used by the v1 REST API:
type
continues to beuser
name
continues to be a String object of the user’s nameid
continues to be the unique identifier for this user
Authorization Objects
The Authorization object and endpoints remain unchanged between v1 and v2. However, we do plan to stop offering non-expiring tokens in the near future, and move to the more-secure expiring access tokens for every app. This change, when finalized, will be backwards-compatible.
For more information on using the OAuth 2.0 authorization code flow, check out the Getting Started guide.
Audit Logs
The Audit Logs API has some minor changes in V2, as described in the following sections.
Request parameters
- Instead of offset-based pagination, this endpoint now supports cursor-based pagination. Therefore the
offset
parameter is removed and replaced with thecursor
parameter. - A new
sorting
parameter has been introduced, which allows you to sort the audit logs in ascending (ASC
) or descending (DESC
) order.
Response body
- The
type
parameter value is nowcursor-list
instead oflist
. - The
offset
parameter is updated tocursor
. To retrieve the next set of results of the collection, set thecursor
parameter in your next request to the appropriatecursor
value returned in the response. - The
nextLink
andprevLink
parameters have been removed.
Updated 3 months ago