Miro Developer Platform: A look under the hood

The Miro Developer Platform has allowed developers to change the way teams work in Miro — providing extra tools and functionality to customize the way users collaborate and interact with Miro as a tool.

After the initial release of Version 1.0 in September 2019, we were blown away at the diversity of integrations and apps our users created. Very quickly we realized the potential of our Developer Platform, but also the limitations that developers were running into.

As Fred Brooks said, “The hardest single part of building a software system is deciding precisely what to build” — and after seeing how the developer community put our Platform to use, we knew they had already outgrown v1. So we gathered around the whiteboard (well, Miro board) and completely redesigned our platform to be even more useful, and all-around more intentional, to continue to empower and inspire developers to build the next big thing.

We’ve just launched Version 2.0 of the Miro Developer Platform, and it wasn’t an easy task. Our Platform team had to focus on the pieces of our developer platform that really mattered, re-vamp and re-start our API endpoints and SDK methods, and invest in documentation and examples. It was a big challenge, but we wanted to build a platform that put the developer experience at the center of its design.

Interested in diving in already, and trying it out? Visit our Developer Portal to start building your first app.

A revamped Web SDK

Our JavaScript-based Web SDK allows developers to create highly-interactive apps inside of Miro, that interact with Miro boards in new and creative ways. We’ve seen some pretty cool things already, and we’re looking forward to what’s on the way.

Updated methods

We’ve updated nearly all of our SDK methods, but we tried to ensure that V2 would feel consistent and intuitive for our original developer community. Many method names have been changed to improve clarity, but the method structures are intentionally similar.

However, we have made one substantial change (which we believe is better for all developers):
In the v1 Web SDK, we relied on polymorphic endpoints to create and update widget items on a board. This meant that the same method call, i.e. `miro.board.widgets.create()`, would have a completely different structure depending on the type of widget being created. This can create unnecessary complexity for developers as they build and debug their applications. In V2, we have introduced independent methods for each item, so that a developer always knows what is expected when calling that method.

// V1
await miro.board.widgets.create({
    type: ‘image’,
    url: imgUrl,
    x: xCoordinate,
    y: yCoordinate,
})
// V2
await miro.board.createImage({
    x: xCoordinate,
    y: yCoordinate,
    url: imgUrl
})

To learn more about these changes and what it means for developers with applications built on V1, please check out our migration guides.

Added items

In addition to revamping our Web SDK methods, we’ve also introduced some new items and properties that allow developers to customize the end-user experience when interacting with a Miro board.

In V2, we’ve introduced AppCards, a new item type that you can customize with custom colors, fields, tags, icons, and more.

App Cards also allow developers to specify unique modal views specific to the card being opened, allowing for a ton of new possibilities when working with Cards — and they work seamlessly with Kanban Boards, Frames, and Tables. They also provide a way to connect to 3rd party tools to create a deep 2-way sync.

Published Types

We’ve also published our TypeScript types for use within your Web SDK projects. Being feature complete, this makes it easy for developers to utilize auto-complete, type errors, and more.

Our NPM package @mirohq/websdk-types is easy to install and configure with any SDK TypeScript project you’re working on (And comes installed by default in our TypeScript starter project from create-miro-app).

Thoughtfully re-designed APIs

The Miro REST API has been updated with a set of new endpoints, an updated structure, and all-around better documentation for developers looking to integrate their applications with Miro’s APIs.

Re-designed endpoints

We have redesigned our REST API to improve the clarity and usage of nearly every endpoint. However, the core structure of each board and item should be familiar to any developer who built an app using the V1 REST API. Most endpoints have been renamed or had their payloads reorganized, and so we have created a side-by-side comparison for every endpoint to make it easy for existing developers to migrate their apps.

Two components of the REST API have undergone more substantial changes:

First, like the Web SDK, the REST API has also been redesigned to replace those polymorphic widget interactions with independent endpoints. Having clearly defined endpoints and payloads creates a consistent developer experience, and makes it easier for new developers to learn how to use a platform.

Second, we’ve revisited the way that relationships between boards, users, and teams are treated via the API. Previously, these relationships were represented as connection entities, adding complexity to simple operations. In V2, these endpoints have been simplified into more intuitive calls, such as Share board or Get all board members.

Added items

We’ve introduced support for several new item types in the V2 REST API, including:

• App Cards
• Documents
• Embeds
• Frames
• Images
• Previews

We’ve also added new properties to many of the endpoints, including more properties for style, position, and more.

Updated OAuth examples

OAuth 2.0 is an integral part of using the Miro REST APIs, but can be cumbersome for developers to set up and configure. To help developers get started quickly and easily, we’ve created several resources centered around the OAuth experience.

Getting Started with OAuth 2.0
NodeJS & Python OAuth examples
OAuth2 tutorial video

With a growing ecosystem of Miro Developers, we plan to continue adding support for more languages in the future.

Upgraded Developer Experience

The main focus of the V2.0 release was to improve the developer experience. This touches upon a lot of areas, such as App Settings, our documentation and examples, and even a re-ignited developer community.

We believe that giving developers like you the support and resources you need will help you build truly powerful apps and integrations, so making these resources available will continue to be a focus for us as we expand the capabilities of the Miro Developer Platform.

Miro’s company mission is to empower teams to build the next big thing, and that’s something we take to heart on the Miro Developer Platform team. We believe that giving developers the support and resources they need to be successful will lead to solutions and integrations that reimagine the way that teams work together. We’re serious about putting the developer first, so we encourage you to ask questions and join the conversation in either our community forum or on our developer Discord.

Finally, we want to give a big shout out to everyone who has helped us build our platform into what it is today. Hearing directly from our developer community was critical to the creation and design of the Miro Developer Platform 2.0, and we are genuinely excited to continue building our Developer Platform together.

We’ve got plenty of additional resources we’re excited to share as well, such as our official roadmap and migration guides. Stay tuned for more content on upcoming features, capabilities, and more right here on our Developer Blog.

Join our team!

Would you like to be an Engineer at Miro? Check out our opportunities to join the Engineering team.