Get Roadie in your IDE with our new MCP Servers
Roadie
← Backstage Plugins Guides
Microcks logo

Backstage Microcks Plugin

Created by Microcks

Microcks is an open source tool for API mocking and testing. It reads common specs like OpenAPI, AsyncAPI, gRPC, GraphQL, and even SOAP. You can simulate services for local work or CI, then check real implementations against their contracts. That keeps teams moving without waiting on dependent systems.

The Microcks Backstage plugin brings those APIs into your Backstage catalog. It connects to one or many Microcks instances, discovers API definitions, then creates API entities in Backstage. It carries over useful metadata like owners and systems. It also adds direct links so engineers can hit mock endpoints or review recent conformance results from the same place.

Typical use cases are straightforward. Centralize API discovery in Backstage. Expose a living catalog that stays in sync as specs evolve. Give developers a fast path to a sandbox mock for local tests. Surface contract test status next to each API so service owners see quality at a glance. If you manage several environments, you can point the plugin at multiple Microcks instances and keep everything aligned across teams.

Installation Instructions

These instructions apply to self-hosted Backstage only.

Install the provider package

Run this from your Backstage app root

Copy 
yarn --cwd packages/backend add @microcks/microcks-backstage-provider@^0.0.7

Configure the provider in app config

Add one or more provider entries under catalog providers microcksApiEntity in app config

Copy 
# app-config.yaml

catalog:
  providers:
    microcksApiEntity:
      dev:
        baseUrl: https://microcks.acme.com
        serviceAccount: microcks-serviceaccount
        serviceAccountCredentials: ab54d329-e435-41ae-a900-ec6b3fe15c54
        systemLabel: domain
        ownerLabel: team
        addLabels: true
        addOpenAPIServerUrl: false
        schedule:
          frequency: { minutes: 2 }
          timeout: { minutes: 1 }

Notes

You can add more environments under microcksApiEntity like prod or staging if you want separate lifecycles

Wire it into the new backend system

Use this if your app uses the new backend system usually apps created with Backstage 1.24 or newer

Edit packages/backend/src/index.ts and add the module before backend.start

Copy 
// packages/backend/src/index.ts

// add this near other backend.add calls
backend.add(import('@microcks/microcks-backstage-provider'));

// existing code
await backend.start();

Wire it into the old backend plugin system

Use this if your app still uses the old backend plugin setup

Edit packages/backend/src/plugins/catalog.ts

Copy 
// packages/backend/src/plugins/catalog.ts

import { CatalogBuilder } from '@backstage/plugin-catalog-backend';
import { MicrocksApiEntityProvider } from '@microcks/microcks-backstage-provider';

export default async function createPlugin(env: PluginEnvironment) {
  const builder = await CatalogBuilder.create(env);

  // other processors or providers here

  builder.addEntityProvider(
    MicrocksApiEntityProvider.fromConfig(env.config, {
      logger: env.logger,
      scheduler: env.scheduler,
    }),
  );

  const { processingEngine, router } = await builder.build();
  await processingEngine.start();
  return router;
}

Where the synced APIs appear

This provider adds API entities to the Software Catalog They show up in the Catalog pages that ship with Backstage No extra frontend package is required

Version guidance

  • Backstage client at least 1.43 use provider version 0.0.7 or newer
  • Backstage client at least 1.31 and less than 1.43 use provider version 0.0.6 or newer
  • Backstage client less than 1.31 use provider version 0.0.5

Changelog

The Microcks plugin has not seen any significant changes since 6 months ago.

Set up Backstage in minutes with Roadie

Get a demo