Node.JS client: the easiest way to integrate with Miro’s API
Using the Miro REST API just became a lot easier with the release of the official Node.js client library! To get started, install the @mirohq/miro-api NPM package and check out our quick start guide.
Client libraries make it easier to access APIs in the language they’re written in. While you can call Miro’s REST API directly by making raw HTTP requests to the server, the client library provides simplifications that significantly reduce the amount and the complexity of code you need to write.
The client library provides the following benefits:
- Documented methods for every REST API endpoint
- Effortless OAuth 2.0 authorization
- Automatic management of access and refresh tokens
- Simple integration with various frameworks and databases
- Automatic pagination
Let’s take a closer look!
Effortless authorization and token management
The library provides a helper that makes implementing the OAuth 2.0 authorization flow easier. It has several methods that you can use during the authorization flow. It implements all the steps in the OAuth 2.0 specification that are needed to get an access token and start making API calls.
When using the authorization helper, you don’t have to manage access tokens directly. The helper will automatically manage access and refresh tokens. Before making API calls, the library will make sure that the access token is not expired and will refresh the token if needed. To keep track of tokens, the client makes use of external storage, which can be customized by passing alternative implementations. We’ve written a quick start guide to get started with the authorization helpers.
Optimized for all use cases
The authorization helper is optimized for applications that connect user accounts in Miro with third-party services. These apps connect to Miro on behalf of the user, and the user will need to link the external service with their Miro account. To make this easier, the client library works with user ids instead of using access tokens directly. This way, you don’t have to think about the low-level details of the API and can focus on writing your application logic.
One of the most common use cases is a 2-way sync application that takes data from an external service and synchronizes it with content on a Miro board — and vice versa. You can find an example of this use case in our guide on 2-way sync between GitHub project cards and Miro app cards.
For various automation and scripting use cases, the client library also allows accessing the API by using a static access token. Some examples include apps that automate common tasks, such as converting data from one format to another, or workflows that automate management of teams in organizations, by using Miro’s Enterprise API endpoints. You can find more examples on our developer portal.
Forget about the details
To make working with paginated endpoints easier, the library includes auto-paginated methods that help iterate overall resources. This is done by implementing AsyncGenerators, which lazy load additional pages on demand. This way, you don’t need to worry about implementing an offset or cursor-based pagination manually, because the library will abstract this away.
Focus on the best developer experience
Node.js client is written using modern JavaScript language features. The package includes Typescript definitions and JSDoc annotations. When using a supported editor, JSDoc annotations provide quick access to explanations for class methods and properties. This makes it easy to explore the client API without having to visit external documentation.
To provide the best developer experience, we’ve made sure to design the library to be human friendly. It has an object oriented design, inspired by fluent interfaces, which makes the code easy to read and understand.
We generate low-level library code based on the OpenAPI Specification from our API servers. This approach allows us to keep the library up to date as we add more API endpoints and make changes to the existing ones. The auto-generated code is then extended with manually written code that makes working with it human friendly. It also allows us to keep the reference documentation up to date with minimum effort.
Get started with a boilerplate
We have also released a new version of the Miro starter kit: create-miro-app. It allows you to generate some of the major pieces of a new app, and now includes support for creating REST API apps. This tool makes it very easy to get started with the new client library. It generates a boilerplate with all the code necessary to run a simple app. Try it out by running:
npx create-miro-app@latestShare your feedback and contribute!
To start using the client, you can visit the quick start guide on our developer portal and have a look at the client reference documentation. If you have any questions or feedback, you can open an issue on GitHub. For technical questions and discussions, join our Discord server or community forum. We’re looking forward to hearing from you!
