APIs with 3scale logo

Backstage APIs with 3scale Plugin

Created by Red Hat

APIs with 3scale is Red Hat’s API management platform. Teams use it to create, publish, secure, and monitor APIs at scale. The Backstage plugin brings that API data into your software catalog. It keeps your catalog in sync with what lives in 3scale, so engineers see accurate API entries without extra manual work.

The plugin reads products and APIs from your 3scale tenant and registers them as Backstage API entities. It can run on a schedule and refresh the catalog as things change in 3scale. That means version changes and environment entries show up in Backstage with the right ownership and system context. Your catalog stays consistent with your gateway and control plane.

Common use cases include central discovery of internal and external APIs, reducing duplicated YAML in repos, and improving onboarding by showing accurate endpoints and metadata in one place. If you manage more than one 3scale tenant, the plugin can pull from several and present a single view in Backstage. This helps platform teams keep governance and visibility simple while letting service teams move faster.

If you already run Backstage for services and docs, this plugin extends it to APIs you manage in 3scale with minimal friction. You keep 3scale as the source of truth, and you give engineers a clear API catalog where they already work.

Installation Instructions

These instructions apply to self-hosted Backstage only.

Install the backend package

  1. Add the backend plugin to your Backstage backend workspace
Copy
yarn workspace backend add @backstage-community/plugin-3scale-backend

Configure the provider in app config

  1. Add a provider entry in app-config.yaml
Copy
catalog:
  providers:
    threeScaleApiEntity:
      dev:
        baseUrl: https://<TENANT>-admin.3scale.net
        accessToken: <ACCESS_TOKEN>
        systemLabel: 3scale
        ownerLabel: 3scale
        schedule:
          frequency: { minutes: 30 }
          timeout: { minutes: 3 }

The schedule keys are required. Default frequency is 30 minutes and default timeout is 3 minutes.

You can add more provider entries under threeScaleApiEntity. Use a different key for each provider such as test or prod.

Set up with the new backend system

  1. Register the backend module in packages backend src index ts
Copy
// packages/backend/src/index.ts
import { createBackend } from '@backstage/backend-defaults';

const backend = createBackend();

// Registers the 3scale provider module with the backend
backend.add(import('@backstage-community/plugin-3scale-backend'));

backend.start();

Set up with the legacy backend system

  1. Register the provider with the catalog builder in packages backend src plugins catalog ts
Copy
// packages/backend/src/plugins/catalog.ts
import { CatalogBuilder } from '@backstage/plugin-catalog-backend';
import { PluginEnvironment } from '../types';
import { Router } from 'express';
import { ThreeScaleApiEntityProvider } from '@backstage-community/plugin-3scale-backend';

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

  // Reads providers from app config and wires them to the catalog
  // Use the same provider key that you set in app-config.yaml such as dev
  builder.addEntityProvider(
    ThreeScaleApiEntityProvider.fromConfig(env.config, {
      logger: env.logger,
      scheduler: env.scheduler,
      providerId: 'dev',
    }),
  );

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

Frontend visibility

This plugin runs in the backend. It syncs API entities into the catalog. No frontend package from this plugin is needed.

If your app has the API Docs page you can browse the synced APIs there. If it is missing add this route.

  1. Add the API Docs page route in packages app src App tsx
Copy
// packages/app/src/App.tsx
import React from 'react';
import { Route } from 'react-router';
import { FlatRoutes } from '@backstage/core-app-api';
import { ApiExplorerPage } from '@backstage/plugin-api-docs';
// other imports

export const App = () => (
  <FlatRoutes>
    {/* other routes */}
    <Route path="/api-docs" element={<ApiExplorerPage />} />
  </FlatRoutes>
);

The synced API entities will also appear in the Catalog pages if you filter by kind API.

Changelog

This changelog is produced from commits made to the APIs with 3scale plugin since a year ago, and based on the code located here. It may not contain information about all commits. Releases and version bumps are intentionally omitted. This changelog is generated by AI.

Breaking changes

  • Remove the dynamic plugin build step from the 3scale workspace. Remove the janus idp cli dependency. If you used export dynamic update your build scripts to the standard Backstage build flow #1790 merged 11 months ago

Features

  • Use ownerLabel and systemLabel config when ingesting 3scale services. This sets owner and system on created entities as expected #4024 merged 4 months ago

Bug fixes

  • Catch errors per entity during 3scale sync. A bad product no longer stops the whole sync #3545 merged 6 months ago

Maintenance

  • Remove support and lifecycle keywords from plugin packages. Also remove dynamic plugin app config from some plugins #4302 merged 3 months ago
  • Clean up vendor and Janus references in package metadata #3476 merged 6 months ago
  • Remove unused dev dependencies in the 3scale backend package. Add a script to rebuild knip reports #2430 merged 9 months ago
  • Fix API report warnings. Remove unnecessary files #2059 merged 10 months ago

Dependencies

  • Update msw dev dependency to v1.3.5 #1907 merged 10 months ago
  • Update msw dev dependency to v1.3.4 #1738 merged 11 months ago

Set up Backstage in minutes with Roadie