Forem: William Bishop

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.

My First Server and REST API: Essentials for Frontenders

William Bishop — Thu, 12 Jan 2023 12:13:17 +0000

Explore the essentials of integrating with 3rd party services, and take your web apps to the next level by getting familiar with the infrastructure necessary to call a REST API from a simple backend, using NodeJS + Express.

REST APIs aren’t just for backend developers or full stack gurus. In fact, incorporating 3rd party APIs into your frontend applications is a great way to expand the capabilities of your app and bring the power of an almost exponential number of external services to your offering.

But in order to get the most out of REST APIs, you’ll need to understand the basics about how to efficiently call them, and what kind of infrastructure you’ll need to make requests from an app of your own. Luckily, it’s not too complicated and we’ve boiled it down to the essentials for you!

Let’s get started!

Understand REST APIs’ role in frontend development
Set up a backend / server
Master an end to end example in NodeJS

Even frontenders could benefit from a backend sometimes!

So, what exactly is the value in leveraging REST APIs in frontend development, and why should we bother with a backend? Well, REST APIs are extremely versatile and open up tons of use cases.

REST APIs can serve as a connection within complex software, or they can stand alone as their own product even. There are many successful companies who have taken an API-first approach, where their open APIs are the primary value driver behind their business model. Some successful examples of this can be seen in companies we've all likely heard of, such as eBay, Twilio, Stripe, and more.

Ebay’s former head of developer ecosystem, Tanya Vlahovic, put it really well:

"...we allow...developer[s] to take all of these building blocks and uniquely combine them [to form]...great quality experiences."

It’s just another reminder that being an Engineer with the ability to confidently leverage REST APIs can open many doors for you.

Alright, but how do we get started? Well, first we’ll need to set up a simple backend and server.

Create a NodeJS project with an Express server

Especially in frontend development, setting up the infrastructure necessary to make API requests (and set up a server) can be a bit intimidating. Maybe it has even prevented you from taking advantage of these capabilities—until now. 😉

While of course there are exceptions to needing a backend and server, such as serverless functions in frameworks like NextJS, we will stick to the basics for now. We’ve boiled down the essentials for getting a NodeJS script up and running, in order to call a REST API in four easy steps in NodeJS:

Set up a NodeJS project
Install Express
Create an index.js file and import Express
Instantiate Express and send a test request

Let’s start from step 1.

1. Set up a NodeJS project

We’ll run through an example in NodeJS. If you aren’t familiar with Node and npm, you can find more details on this here.

To set up a new NodeJS project, we’ll need to first create a new directory to house a package.json file. Within this new directory, we can then run the following command in our terminal:

npm init -y

This will generate a package.json file for us, which is essentially a simple manifest of sorts for our NodeJS script, which by default will take place in index.js. (You can use another filename if you like, just be sure to update your package.json!)

2. Install Express

Now that we have our Node project created, we will run the following command within our project directory, which will generate a node_modules folder and a package-lock.json file — two essential components for housing resources and versioning our Node app:

npm install --save express

3. Create an index.js file and import Express

Next, we can create our main script, index.js, and import our Express server instance.

First, create an index.js file within the same main directory. At the top of this file, we can import Express using the following statement:

const express = require(“express”);

4. Instantiate Express server and send request

And lastly, we can now instantiate our Express server and send a test request to a simple GET endpoint in our app.

First, we instantiate Express using this command:

const app =  express();

Next, we create a GET endpoint, from which we’ll send a simple response to the browser:

app.get(‘/’, (req, res) => {
    res.send(‘hello world’);
});

And lastly, we need to specify a port for our server to listen on—let’s use 3000:

app.listen(3000, () => console.log(`Listening on port ${port}!`))

And now we can run our script…

node index.js

…and navigate to localhost:3000 in our browser. On success, our terminal should show the console log that our app is listening. And if we go to our browser at localhost:3000, we should see the "hello world" text that we included in our endpoint.

Of course, this is a simplified walkthrough of how to set up a server in NodeJS, using express, so you may need to add or tweak a few lines of your own — but these are the main steps necessary.

But just setting up a server by itself isn't super useful, right?

So, instead of simply sending some "hello world" text to the browser within our app.get() function, we could instead make a request to a REST API within this function, and utilize the response in another part of our app. Or, we could send the response from such a request to our browser, similar to our hello world text in the above example.

Let’s move on to an example script.

Making an API request from a NodeJS script

At Miro, we have several sample scripts that demo this flow. Let’s take a closer look at an end to end example of calling a REST API from NodeJS with our node-oauth repo, which you can clone here:
Miro node-oauth repository

First, we’ll follow similar steps as before in setting up our index.js file, and we will additionally use two other packages—dotenv for working with sensitive variables, and axios for making http requests:

// Require sensitive environment variables (Client ID, Client Secret, Miro Board ID)
require("dotenv/config");

// Require Axios for handling HTTP requests to Miro /oauth and Miro API endpoints
const axios = require("axios");

// Require ExpressJS for local server
const express = require("express");
const app = express();

// Call Express server
app.get("/", (req, res) => {...]

Within our app.get() endpoint, we will call the Miro REST API, but first let’s continue setting up the rest of our script by making sure our server is listening at a specified port. We’ll put this at the end of our script:

app.listen(3000, () => console.log(`Listening on localhost, port 3000`));

Now, back to the app.get() function. Within here, we’ll do two things:

Retrieve an access_token for the Miro REST API, by calling Miro’s OAuth2.0 endpoint
Call a Miro REST API endpoint to retrieve a Miro Board using our access_token, and send the response to the browser

In line 36 of index.js, we’re calling the OAuth endpoint.

And in line 63 of index.js, we’re calling Miro’s GET Board endpoint, using the access_token we retrieved in line 36.

And finally, we’re sending the response to our browser, in line 68 of index.js.

Master REST APIs with Miro

Want to walk through this script in a bit more detail and see the output in the browser? Check out our on-demand educational training series, REST API Essentials for Frontenders, linked above!

And keep going with REST APIs, leveraging the Miro Developer Platform’s assortment of sample apps!

You can even create a developer team and start quickly calling Miro’s REST 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 REST APIs and how to leverage the Miro Developer Platform? For more inspiration or questions, follow along with our Developer Community on YouTube, GitHub, and Discord.

Taking the fear out of authorization: OAuth essentials for frontenders

William Bishop — Mon, 12 Dec 2022 12:50:01 +0000

Explore the essentials of OAuth2.0, and how to take your web applications to the next level by removing the complexities around integrating 3rd party REST APIs in frontend development.

OAuth2.0 is one of the most commonly dreaded authorization methods to implement in frontend development - and understandably so! With its various flows, exchanges, and other intricacies, it can be overwhelming. But, it's also an essential authorization flow that opens the door to a seemingly unlimited number of 3rd party use cases.

Let's take the fear out of OAuth2.0!

Understand OAuth's role in frontend development
Explore common flows, or grant types
Master the authorization code flow

OAuth2.0 isn't just for backenders

If you're a frontend developer, you've most likely encountered OAuth2.0 in some capacity, but perhaps you've never needed to fully implement it in your own applications, or it was handled separately in backend development.

But actually, OAuth2.0 is an essential authorization flow for all types of developers. And by equipping yourself with the context and confidence necessary to implement it all on your own, you open up the door to new capabilities to complement the native ones you've already built. Not to mention, there might come a time, even in frontend development, when you're tasked to incorporate some of your end users' favorite tools like Miro, Google, Zoom, and more.

So, let's remove some of the complexities that can cause us to avoid OAuth2.0 in the first place.

OAuth2.0 flows in a nutshell

OAuth2.0 supports various different "flows", or grant types, as you'll see them officially referenced. These are essentially just different ways of getting to the same end-goal: receiving authorization to work with some type of resource (via an API).

Source: OAuth.io

However, there are many different flows, and they apply to a variety of different use cases or implementations. You can find the full list and explanation of each flow on OAuth.net, but let’s cover a couple of the more common ones now.

Authorization Code

The authorization code flow is one of the most common flows, especially in frontend development, where it’s expected that an end-user will provide their authorization in some sort of frontend UI.

PKCE

PKCE is an extension for the authorization code flow, originally intended for mobile development. However, it was found to be an effective mechanism for all mediums, and is used to prevent CSRF and authorization code injection attacks.

Implicit Grant

You may see this referenced, but it’s a legacy flow, and no longer a best practice/recommended grant type to leverage. It was found to be vulnerable to bad actors/risks upon returning an access token directly in an HTTP redirect (without any kind of exchange like in the authorization code flow).

Mastering the authorization code flow

Despite being one of the most popular implementations of OAuth2.0, the authorization code flow can seem daunting at first, given the number of steps. But once it’s broken down a bit, things become much simpler. There are 5 main steps in this flow:

End user authorization
Exchange of the authorization code
Retrieval of an access token
Request to the resource server
Refresh of the access token

Let’s lay things out in layman’s terms and use some sample code snippets from a sample app we’ve built in NextJS.

First, a user of your application will need to provide their consent, or authorize your application to access data on their behalf. This is step 1, and occurs when the end user is directed to the authorization URL that your app constructs, based on the resource owner (e.g., Miro, Google, etc.).

Here’s an example function, where the two environment variables included are: a Miro-provided Client ID, and a specified callback URL, respectively:

export default function handler(req, res) {
 res.redirect(
 "https://miro.com/oauth/authorize?response_type=code&client_id=" +
 process.env.clientID +
 "&redirect_uri=" +
 process.env.redirectURL
 );
}

(You can find a more detailed explanation of constructing this URL in Miro’s OAuth2.0 starter guide as well.)

Next, your application will need to receive a code parameter from the redirect url, immediately following the end user’s consent, and exchange this for an access_token — this all happens on your app’s backend/server. This is steps 2 and 3, respectively:

import axios from "axios";

export default function handler(req, res) {
  let access_token;
  let refresh_token;

  if (req.query.code) {
    let url = `https://api.miro.com/v1/oauth/token?grant_type=authorization_code&client_id=${process.env.clientID}&client_secret=${process.env.clientSecret}&code=${req.query.code}&redirect_uri=${process.env.redirectURL}`;

    async function grabToken() {
      try {
        let oauthResponse = await axios.post(url);

        access_token = oauthResponse.data.access_token;
        refresh_token = oauthResponse.data.refresh_token;

        if (access_token) {
          console.log("access_token = " + access_token)
          console.log("refresh_token = " + refresh_token)

// {{ Some code here to store or leverage this access token }}

          res.redirect("/");
        }
      } catch (err) {
        console.log(`ERROR: ${err}`);
      }
    }
    return grabToken();
  }
}

After this, your app can leverage this access_token you retrieved in the previous step, and use it as the value of the bearer token that your app will authorize any subsequent API requests to (for the particular resource the access token belongs to — e.g., Miro REST API). This is step 4. Here is an example of a function that makes a request to the Miro REST API, using the access_token retrieved in the last step:

import axios from "axios";

export default function handler(req, res) {
  const headers = {
    Accept: "application/json",
    "Content-Type": "application/json",
    Authorization: `Bearer ${access_token}`,
  };

  axios
    .get(
      "https://api.miro.com/v2/boards",
      {
        headers: headers,
      }
    )
    .then(function (response) {
      res.json(response.data);
    })
    .catch(function (error) {
      console.log(error);
    });
}

And lastly, it’s important to note that access tokens aren’t valid forever (technically, they can be — but this is not a best practice, and it’s considered a security vulnerability to have non-expiring access tokens). A typical access_token is valid for some amount of time — usually 60 minutes — and then a new access token should be requested, using a refresh_token. (A refresh_token is typically returned alongside your original access_token in step 3, depending on your resource owner’s configuration settings.).

While it’s admittedly a few steps end-to-end, it helps to visualize things a bit. Here’s a high-level overview of each of these 5 steps, and their interactions between the end user, an application, and the resource owner (again, this could be Miro, Google, etc.).

Master OAuth2.0 with Miro

Interested in going deeper with OAuth2.0? Check out this on-demand educational training series, OAuth Essentials for Frontenders, linked above!

And keep going with OAuth2.0, leveraging the Miro Developer Platform’s assortment of sample apps!

You can even create a developer team and start quickly calling Miro’s REST 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 OAuth2.0 and how to leverage the Miro Developer Platform? For more inspiration or questions, follow along with our Developer Community on YouTube, GitHub, and Discord.

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.