Lifecycle policy

This policy is designed to help developers understand how to use Miro's REST API and Web SDK at various stages of their lifecycle, including experimental and general availability. It aims to ensure that developers can build robust and stable integrations with our platform by following best practices for versioning and migration.

Definitions

• Experimental: Features that are under development and not recommended for production use. They may be unstable and are subject to change without notice.
• General Availability (Production): Fully stable features that are safe for use in production environments. Breaking changes are unlikely and will include a deprecation period before retirement.
• Deprecation: The stage where a feature is being phased out. No new features will be developed, and only critical bugs will be fixed. A minimum period is provided before the feature is retired.
• Retirement: The final stage where a feature is no longer supported and should not be used.

Lifecycle stages for product capabilities

The table below details our current policy in the context of our product lifecycle. For information on the introduction of new features for the REST API and Web SDK, see our Changelog.

For more details on how to access experimental features via REST API and Web SDK, see:

• REST API experimental capabilities
• Web SDK experimental capabilities

REST API

REST API endpoints suitable for use in production include the major version in the path URL. For example, if the latest version of an API is 2, an example URL will be:

https://api.miro.com/v2/boards

There will be one official, major version of the Miro REST API at a given time, which is the recommended version for new or migrated production-level integrations.

REST API experimental capabilities

REST API production endpoints may have a corresponding experimental endpoint, which is used to preview potential future versions of the endpoint.

Experimental endpoints under our REST API are reflected in the path URL:

https://api.miro.com/v2-experimental/webhooks

We aim to offer experimental REST API versions for a period of at least three months before moving to production, but this may be subject to change. In some cases, we may determine that an experimental version is not suitable for use in production. In this scenario, there may be multiple updates to an experimental version before one is identified as suitable for moving to production.

Migration period

When experimental capabilities are moved to General Availability (Production), they will remain available on the experimental endpoint for a minimum period of three months before being deprecated. During this time, developers must migrate their integrations to the production environment.

If your application relies on features that are exclusively available in an experimental version, you leverage this at your own risk, as Miro reserves the right to discontinue experimental features before they are promoted to the production endpoint, or make changes to new features that are not backwards compatible. For this reason, we do not recommend using experimental versions in production environments, or to support business-critical workflows.

Web SDK

There will be one, official, major version of the Miro Web SDK at a given time, which is the recommended version for new or migrated production-level integrations. When breaking or backwards-incompatible changes are made to the Web SDK, these will be announced in advance.

Changes that do not impact the functionality of existing applications, such as new methods or properties, may be released at any time, and are communicated in our Changelog.

Web SDK experimental capabilities

Features that are still under development or testing will be labeled in the documentation as “experimental”. Features labeled as “experimental” may change in ways that do not preserve backwards compatibility, and they may be withdrawn at any time. For this reason, we do not recommend using features labeled as “experimental” in production environments, or to support business-critical workflows.

Experimental namespace

Experimental capabilities in our Web SDK are reflected in the experimental namespace within the SDK:

miro.board.experimental.createItem(...);

Querying experimental items

When querying for existing items on the board, only elements considered stable are returned. For example, if an item such as a mindmap is marked as experimental, the following query operation does not return mindmap items:

// this includes only stable items. Example: mind_map isn't returned 
await miro.board.get({ type: ['sticky_note', 'card', 'mind_map'], });

To return experimental items together with stable items, it is necessary to invoke the experimental namespace:

// this includes both stable and experimental items 
await miro.board.experimental.get({ type: ['mind_map'], });

Experimental events

There may be times when the Web SDK introduces experimental events. In these instances, experimental events are prefixed with experimental. For example:

miro.board.experimental.on('experimental:items:update', ...)

A message will be displayed letting you know that you’re working with an experimental feature. For example:

Thank you for trying out ${experimental_feature}. It's an experimental feature, and it may change without notice. If you encounter any bugs, please share them with us. Thank you!

By following this policy, you can effectively leverage Miro's REST API and Web SDK capabilities while minimizing the risks associated with using experimental features.