DEV Community: Miro for Developers

Bring visual collaboration to life with Postman and Miro APIs

William Bishop — Wed, 30 Aug 2023 10:40:52 +0000

This article was originally published on the Postman blog on August 18th, 2023.

With the power of Postman, the options for dynamically creating content with third-party platforms and tools are seemingly endless. This was the inspiration for a recent Postman livestream exploring how we can leverage the Miro Developer Platform's REST APIs to create content on a Miro board - all from within Postman.

Before diving into the details of how you can streamline your workflow with Postman and unlock new possibilities in Miro, let's start with a quick primer: what is visual collaboration in Miro? Well, simply put, it's a collection of connected activities that allow you to communicate and collaborate across formats, tools, channels, and time zones - without the constraints of physical location, meeting space, and whiteboards.

The Miro Developer Platform allows you to extend the power of visual collaboration and interact with Miro boards via its robust suite of REST APIs.

Getting started

In order to use the Miro REST API with Postman, you’ll need to first make sure you have a Miro account and some developer credentials to generate an access_token. You can find all the necessary details to get started here.

Miro Postman Collection

To make things even easier, you can leverage the Miro Developer Platform public collection in Postman, which includes an authorization helper to make getting an access token a breeze. By simply entering any Miro endpoint into Postman, you’ll see an option to set up a new authorization method, providing a frictionless experience for accessing Miro’s APIs (more details on this awesome new helper here).

Generating sticky notes dynamically from Postman

Once you’ve authorized and have your access_token saved to your Postman environment, you’re ready to make a request to the Miro API.

But rather than just make a single request that, for instance, creates a sticky note on a Miro board, let’s take advantage of Postman variables and the Postman Collection Runner feature to automate a number of requests, using some content from outside of Postman.

To do this, we can navigate to the Sticky Notes folder in the Miro Developer Platform collection, and leverage the Create Sticky Note Item endpoint. Navigate to the Body tab in Postman, and you’ll see some JSON already populated for the body of the request. For the content field in the request body, we can create a new environment variable—{{content}}. We can do the same for the x, y fields in the position object—{{x}} and {{y}}.

Now, in the request URL, we will need to pass the ID of a Miro board under the team we authorized when we set up our authorization initially. If there aren’t any boards, simply create a new one from the Miro dashboard.

Hit Save and let’s populate these variables from some content outside of Postman.

Generate sticky notes from CSV file

To start, we’ll need a .csv file that we can work with. Let’s create a basic .csv file where the first line is our header, and the following lines are the content and coordinates that we will feed into our requests in Postman to create sticky notes via the Miro API.

Once we’ve got our .csv file set up, we can use the Postman Collection Runner to select the request we’ve already set up for the Create sticky note item endpoint and choose a number of iterations. We’ll do just a few iterations, and select the .csv file we created for the Data File Type. Hit Run Miro Developer Platform and go to the Miro board you specified in the Create sticky note item request earlier.

Voila! We can see our new stickies being generated from our .csv file as the Postman Collection Runner initiates.

While this is a simple example, you can imagine how many possibilities there are to combine the power of Postman and Miro to generate and manipulate content on a Miro board! But don't just take my word for it - you can take it even further.

Expand your workflow with Postman Flows and Miro

Interested in exploring further automation? Check out how we leveraged Postman Flows to add some more complexity to our variables and inputs in an effort to create even more dynamic workflows between Postman and Miro.

That's a wrap!

In addition to the capabilities we demonstrated here, there's so much more you can do with Postman and the Miro Developer Platform. Want to keep going? You can also build applications with Miro's Web SDK for a frontend experience directly on a Miro board, and use Miro's REST API for authorization and further automation.

This article was originally published on the Postman blog on August 18th, 2023.

How the Miro Developer Platform leverages contract testing

Elena de Graaf — Mon, 15 May 2023 16:12:29 +0000

Design-first approach at Miro

The Miro Developer Platform 2.0 was launched last year, and since then we’ve been working on improving the quality and consistency of our REST API. To achieve this, we decided to embrace a design-first approach. For us, it meant designing the API before actually implementing it, and making sure that the quality was high during the whole development process.

This meant we needed an efficient way to verify compliance between the API and its description in OAS (OpenAPI Specification) files.

In this post, I’ll share why we landed on contract testing as the solution. Contract testing is a fast, lightweight form of API testing that ensures two separate services are compatible and can communicate with each other by checking the consistency with a set of rules.

Switching from code generation

Previously, we generated OAS files from the code, using annotations on controllers and models. At the time, this allowed us to transition from writing the documentation manually to some degree of automation. However, the solution was hacky and required us to jump through a lot of hoops to generate the OAS files.

@Operation(
   summary = "Get specific connector",
   description = "Retrieves information for a specific connector on a board.",
   responses = [
       ApiResponse(
           responseCode = "200",
           description = "Connector retrieved",
           content = [
               Content(schema = Schema(implementation = ConnectorWithLinks::class))
           ]
       )
   ],
   operationId = "get-connector"
)
fun getConnectorById() {...}

The early version of the API was not designed according to OpenAPI standards and had problems like conflicting endpoints and overly complex models. The main components of the design-first approach were quite difficult to implement, so we decided to switch the source of truth from the code-generated OAS files to permanent, curated ones.

How do we keep it in sync?

However, switching the source of truth presented a new problem. When the OAS files were generated from the code, we could at least partially guarantee that we were serving what we were promising. For example, the endpoint description could not have been generated if it didn’t exist in the code. Now, there was no way to tell if the OAS file had the paths and schemas that actually existed.

Looking for a solution

Of course, we have end-to-end tests. Why not reuse them to verify that the API looks as expected? They cover the functionality anyway, so why not add a little schema validation to the mix?

This idea is great, but it has the same flaw as the previous situation — it’s based on trust and leaves room for human error: New endpoint, but tests are not added? New parameter added, but tests are not updated because it’s out of critical path? The whole new experimental API appeared with no new tests and no intention to write them yet?

Writing a set of tests just to verify the compliance between the API and its description in OAS seemed even more far-fetched — not only did it have the same flaws, but it would also require us to do the same work all over again.

And this is how we arrived at the idea of generating tests from the OAS file.

How can a test be generated?

Our OAS has all the necessary data to successfully generate a request and validate the schema of the response. The request body can be built from schemas and the provided example/default values. If we don’t go into the details (and we don’t just yet), the logic for one resource is pretty easy:

First, find the endpoint that creates the resource (for example, the widget).
Save the id from the response.
Re-use it in all other endpoints (get widget by id, update widget).
Find the endpoint to delete it and execute it last.

But the devil is in the details, and the most pressing questions would be: What if it’s more than one resource? How do we guarantee that, say, the widget is created before the board is deleted?

Level-method model

At this point we cared about two things: the method (POST should go first, DELETE — last) and the order of resource creation (boards before widgets). It may seem to have a simple solution.

We can easily identify the endpoints that create/delete the resources by method; that’s the first point of comparison. When we look at the path, we see that some resources appear before others. By naming them resource 1 and resource 2 (3, 4 or however far the craziness can get us), we get the second point. Then we only have to sort in the form of an arrow:

This idea was simple, easy to understand, and worked great as a proof of concept, but it introduced more problems than it solved, namely:

Representing the order in a simple manner possible with two levels of resources, worsens with three levels, and becomes not maintainable after it.
Not all POST endpoints create resources. For example, attaching a tag to the item is also a POST endpoint, but it has to happen after both items and tags are created.
Adding additional order — for example, if the endpoint has parent_item_id, it has to be created after a frame is created — seems impossible without blowing up the complexity.

We needed a more powerful way of sorting the relationships between endpoints, and that led us to a dependency graph.

Dependency graph

Who would have thought to represent dependencies with a graph, right? In any case, it seemed like a very plausible solution: A directed graph can handle relationships of any complexity. It’s very clear what should be executed first. And there’s no need to rely on strict pre-defined ordering.

But how do we build a graph? Do we take the very first endpoint and put it in the graph, then take the next one and try to determine its relationship with the first node? That might work — and guarantee that the board is not deleted before we’re done with widgets on it. But at some point this approach would require traversing the entire graph to figure out the relationships with all other nodes. Despite the fact that we’ll never have that amount of endpoints for it to become a real performance problem, it does not help with the complexity, so we probably need another approach.

Luckily, the level-method ordering approach highlighted not just the problems, but also the way we can use components of the url to determine the relationships. So instead of trying to fit the endpoint into the graph, we’re going to build the graph around it based on what this particular endpoint needs.

Walkthrough

Let’s take a simple endpoint: add a tag to an item. By looking at the endpoint, we can see that before it can be executed, we need to have a board, an item, and a tag already created. We’re going to have a special kind of node — “creational” nodes — and will create a lot of “empty” nodes like this. They can be populated with an actual url template when we get to it, but the node needs to exist before, so it can be used as a dependency.

What are the steps to building a dependency graph for this endpoint?

Create a graph node for current operation.
If the node creates the resource, save it to the map of resources and their corresponding creation nodes.
For each required parameter or resource in the api path:

Find the node that knows how to create the required resource from the map above.
…or create an empty node that will be populated when the creation operation is parsed.
Add a dependency on it.

What if the endpoint deletes the resource entirely? Instead of adding extra complexity to the algorithm, we save them separately, in a “cleanup queue.”

Now we have a graph of all the endpoints, plus a cleanup queue with delete endpoints sorted by the level of the resource being deleted. To test all the endpoints as parameters in the test, we need to put them in a simple sorted list. The initial idea was to use a graph and modified topological search, but with the graph construction that we use, the sorting is simplified to a BFS plus polling the cleanup queue in the end.

As you may have noticed in the above example, an endpoint node can have a dependency on more than one other node, for example, both tags and items. And they, in return, can depend on multiple other nodes. The simple BFS will create duplicates at best, and unexpected ordering in the worst-case scenario. Plus, even duplicates can be detrimental: A second tag is created with the same example value provided in OAS, and this request ends with 400 because duplicated tags are not allowed.

The solution for this, however, would be simple: If some node meets a child with more than one parent, it ignores it and detaches itself from a child, leaving nodes that appear later to take care of. This is the cruel reality of child care in computer science.

Of course, there are still some limitations to what can possibly be automated. Here are some of them:

If the resource cannot be created via API (e.g. organizations for enterprise API), it has to be created before the test runs.
If the endpoint has a parameter (e.g. tag_id or parent_item_id or parent_id), you need to map it to some resource first (e.g. tag_id to tags).
Likewise, if another resource is mentioned in the request body, it has to be created (e.g. widgets for connectors) or mapped to an existing resource.

Customizations

The whole solution consists of 4 parts:

The OAS files describing the Miro API
Test generation logic
Creation of the components that can be generated automatically
The tests themselves

Plugins

The test generation logic is a separate library that only needs to change when a new feature is required for all test suites, for example, when we decide to also make requests with missing required parameters to test error responses. All custom modifications, including providing new OAS files, have to go through plugins.

Plugins offer a set of customizations to the owner of the API. For example, mapping resources to parameters, or retrying logic for some endpoints.

Other types of tests

The initial set of tests contained only positive tests that check that a successful response is returned and the response schema is exactly as it is described in the OAS file. However, there are a number of possibilities to create other types of tests, from the already mentioned missing required parameter checks, to testing the expected error responses.

Automation

The tool is as good as its automation, so the API testing tool is scheduled to run frequently and to notify the team about the results. This solution also unlocked not just publishing the documentation automatically right after the change, but also preparing OAS files, for example, removing endpoints marked as drafts.

There you have it. With OAS contract testing, we can verify compliance between the API and its description in OAS files.

Do you have ideas or a different approach to API testing? Let us know in the comments — we’re interested in what you have to say!

Are you interested in joining our team? Then check out our open positions.

Finally, don’t forget to try the Miro Developer Platform for yourself.

Harnessing the power of React Server Components + Miro in NextJS

William Bishop — Tue, 04 Oct 2022 12:49:58 +0000

This post was updated October 2023 to reflect the latest React Server Component capabilities.

An in-depth look at React Server Components and how you can take advantage of this now stable feature using our NextJS starter app.

With the introduction of React 18 in 2022, React Server Components (RSC) were initially introduced as an experimental feature. Since then, they've matured into a stable capability with a lot of great benefits. Follow along as we explore the basics of what React Server Components are, how to effectively build them in the context of our NextJS sample app, and what to expect from RSC in the near future as the capability continues to evolve!

We’ll cover:

Benefits and limitations of RSC
Quickstart: Writing a React Server Component
Current and future state of RSC
RSC x Miro (explore our sample app!)

React Server Components: Why use them?

There’s a reason that React has invested time and resources developing React Server Components (and partnered with Vercel/NextJS): they’re efficient, in-demand by developers, and offer simple ways to improve the overall performance of any dependency-heavy application.

React Server Components render server-side first. By rendering React components server-side first, it means we can enjoy each of the benefits below. 🤓

Improved performance

Reduce the load time for apps with big bundles
Since RSC are not included in the app bundle, they don’t contribute to its size, meaning smaller bundles and apps overall (see the MomentJS example above)

Direct access to your backend

RSC allow direct access to your backend and database, enabling fast data fetching

More dynamic than standard server side rendering

RSC can be re-fetched multiple times to re-render data (unlike traditional server side rendering, which typically happens once—on initialization)

Use them alongside client and shared components

You can use a mix of client side and server side components (denoted by their extension), as needed. Shopify does a great job of visualizing this: (Source: Shopify, Custom Storefronts / Hydrogen / Framework / RSC)

As with any newer capability, there are going to be aspects that are continuing to evolve, or perhaps some unanswered questions about which direction things are headed in the future. We’ll call out what we do know later on, but it’s a good time to be explicit about some current limitations (as of this writing):

Again, RSC are continuing to evolve, stay up to date on the latest in the official NextJS documentation
RSC are not intended for the interactivity that a typical frontend or set of client-side components would offer. They should be used thoughtfully, and aren’t an answer to all our frontend woes!

It’s strongly recommended to stick to the NextJS structure for leveraging RSC (instead of trying to create your own, standalone react server component bundles), due to the complexity and evolving nature of RSC.

Get your hands dirty

With the stable release of RSC in NextJS, we decided to get our hands dirty and have some fun.

And speaking of sticking to the NextJS structure/boilerplate for leveraging React Server Components, that’s exactly what we’ve done in our Miro app. In addition to testing out RSC, we wanted to add a little bit of our own twist to things. So, we created a Miro-inspired application that both helped us explore RSC and create a more visually robust app. As a bonus, we used Miro as our authorization provider in order to kill two birds with one stone. 😎

You can clone the moment-time branch of our GitHub repo and start playing around. To get up and running:

Clone the repo
From the root, run git checkout origin/moment-time
Create a .env file with the following credentials:

MIRO_CLIENT_ID=""
MIRO_CLIENT_SECRET=""
MIRO_REDIRECT_URL="http://localhost:3000/auth/redirect/"

Reference the README.md for steps to generate Miro Client ID and Miro Client Secret
Run npm install
Run npm run start and visit localhost:3000

Before diving into our starter app, you’ll want to make sure you’re up to speed with the basic conventions for writing react components, and it doesn’t hurt to review the official NextJS documentation on React Server Components.

By default, any components included in the app directory of your NextJS app will be rendered on the server as React Server Components. See an example in our app's page.tsx file, where we import a large package, MomentJS. But because this component is within the app directory, it will render server-side first and the frontend bundle size will remain untouched.

You can also use client components within the app directory, but you will need to be explicit about this in your component file. This requires the use client directive to ensure the file is loaded client side. See an example of this in our TimeDifference.tsx file, where we create a client component to show the change in time in realtime. This is an example of how you might use client components to complement server components — for situations where you want to add interactivity (think of timers, stock updates, flight details, etc.).

Write your first React Server Component

Write your first React Server Component in NextJS, in just a few simple steps:

Inside your NextJS project, navigate to the app directory
Create a new component
Call this component from the main index.js page (or if you're using our sample app, page.tsx).

This component should render server-side first. To verify, load page.tsx (or whatever page you wish to call the component in) and check out the page’s source code. You’ll see your server component reflected directly in the html markdown.

Miro Sample App

Let’s take a look at a specific example in our sample app here. We’re leveraging the moment.js NPM package to generate today’s date-time server-side. In our page.tsx file, we’re importing MomentJS and returning it in our HTML.

// app/page.tsx
import moment from 'moment'
[...]

return (
  <div className="grid wrapper">
    <time>
    {moment().format('MMMM Do YYYY, h:mm:ss a')}
    </time>
  [...]
  </div>
)

And when we go to our app and inspect the page source, we’ll see our server component has been directly injected into the HTML on our frontend:

In contrast, when we look at TimeDifference.tsx in our sample app, we are using the use client directive at the top of the file to ensure the component is loaded client-side. You'll notice in the page source this is reflected as follows, since the time difference is rendered client-side:

Further exploration

Okay, so we’ve talked a bit about RSC and we’ve seen how we’re using it in our Miro sample app—but this is just the tip of the iceberg!

We’ve used the MomentJS example to leverage RSC in our app, but there are other use cases that you can test out. Here are a couple of ideas to keep the momentum going:

Create a new server component in our sample app that leverages a different dependency. For example, any larger NPM packages are great candidates to keep server-side!
Take an existing or older React app of your own and groom through your components to see if you’re currently including any heavy dependencies on your frontend. If so, try and convert these to server-side components!
Show us what you build!

The state of RSC: Now and next

We’ve only scratched the surface of using React Server Components, but there’s so much more that can be done to leverage their efficient, performance-improving abilities.

Luckily, the NextJS team thinks so too, so they’ve included it in their latest stable releases and we can look forward to more improvements in the future.

Build the next big thing with NextJS and Miro

If you found this quickstart on using React Server Components and our sample app helpful, let’s keep it going!

Build any app or integration that leverages React + Miro’s REST API, Web SDK, or Live Embed, and share it with us on our developer community Discord server!

Any functioning app that leverages one of these Miro capabilities is eligible to potentially be promoted more broadly in our community, and we’d love to share some exclusive Miro swag with you. 🚀

Check out our other sample apps for some more inspiration. We can’t wait to see what you build!

Did you like seeing how you can leverage the Miro Developer Platform in conjunction with React? For more inspiration or questions, follow along with our Developer Community on YouTube, GitHub, and Discord.