Bring diagrams to life with the power of Miro’s REST API + PlantUML

A behind-the-scenes look at how we leveraged our v2 REST Connector endpoints and Web SDK to convert external code to diagrams in Miro

We recently introduced the Miro Developer Platform 2.0 as our next generation solution for developers to build custom apps and integrations on top of Miro, and we know that there’s no better way to prove this than to show you ourselves. 😉

One of the most valuable use cases for our developer platform is the ability to import 3rd party data, or architecture, into Miro so that the power of collaboration is accessible in one flexible, visual manner.

To explore this, the Miro Engineering team participated in an internal Miro Hackathon (if you haven’t heard about our Hackathons, they’re super creative and a ton of fun — read about our retro Summer Hackathon) and developed an integration to generate diagrams in Miro based on external PlantUML code.

Rather than keep this treasure to ourselves, we decided to open-source the project and write a comprehensive technical walkthrough of the code. This let us highlight the art of the possible with the combined power of our developer platform and a 3rd party capability. Here’s a sneak peek of what we built:

Exploring PlantUML

For those who might be less familiar, UML is a Unified Modeling Language, and continues to serve as one of the industry standards for basic diagramming.

Most importantly, we needed a capability — preferably open source — that was simple enough, but still allowed us to visualize diagram components from a very basic, text-centric starting point. Check, and check!

The open source PlantUML library was exactly the comprehensive 3rd party solution we needed to bring our idea to life.

The tech stack

Our Miro PlantUML app is built primarily in Java/Kotlin and highlights JavaScript/Typescript for the frontend client components of the Miro Web SDK. The full stack looks a bit like this:

• Backend: Kotlin/Java
• Frontend: JavaScript/TypeScript
• Open-source Plant UML library
• Miro REST API
• Miro Web SDK

Leveraging Miro’s Web SDK and REST connector endpoints

Our favorite part about the Miro PlantUML app is that it highlights both the Miro Web SDK and REST connectors. We tried to keep it as intuitive as possible from an architectural perspective.

Within the project, the frontend client (the Miro Web SDK) and our REST API are housed within a client/v2 folder of their own, and the PlantUML resources are neatly referenced from their own src/main/kotlin directory. You can find the full details of how the project is organized in our in-depth Miro PlantUML guide.

To handle the construction of diagrams in Miro, there are a few different components. First, there is the frontend client that provides the input for PlantUML code by an end user, using our Web SDK.

On submission, this calls one of the services in the app to translate the UML, and uses the PlantUML library and its associated resources for this.

Next, there’s the Miro REST API, which is used to construct the lines and arrows that make up a diagram from the PlantUML code.

The following folders contain the code that calls Miro’s REST Connectors:

src/main/kotlin/com/miro/miroappoauth/client/v2
src/main/kotlin/com/miro/miroappoauth/client/MiroPublicClientV2.kt

Within client/v2, the following files determine the style, shape, and position of the connectors:

• File: ConnectorStyle.kt determines the startStrokeCap, endStrokeCap, strokeWidth, strokeStyle, and strokeColor fields within the API’s style object.
• File: CreateConnectorReq.kt determines the startItem, endItem, shape, and positioning (snapTo property) fields of the connector request.
• File: LineShape.kt determines the shape of the connectors (straight, elbow, curved)

The API is called explicitly in lines 69–81 of the file MiroPublicClientV2.kt

You can find the exact properties detailed a bit more explicitly in our API reference documentation for connectors.

While we’ve only just scratched the surface here on the technical details, you can reference our full guide on the app to get an end-to-end understanding of the project.

Create your own diagramming or mapping application

Interested in creating your own app to map or diagram 3rd party data structures in Miro? No problem. We’ve done our best to share the resources and documentation necessary to leverage the Miro Developer Platform for exactly this.

You can use our Web SDK, REST API, or both to create an app for a similar use case, or you can consider forking our Miro PlantUML repo to serve as a foundation for getting started.

Our Miro PlantUML guide even explains where and how to alter the existing app for an alternative 3rd party use case.

Get Started!

Like what you’ve seen? Get started on your own custom app or integration! Create a developer team and start quickly calling our APIs directly from our documentation. You can find the full Getting Started flow here.

Let us know what you build! We’re always happy to talk shop with fellow developers. 🙂

Did you like learning more about how to leverage the Miro Developer Platform? For more inspiration or questions, follow along with our Developer Community on YouTube, GitHub, and Discord.