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
- Add the backend plugin to your Backstage backend workspace
yarn workspace backend add @backstage-community/plugin-3scale-backend
Configure the provider in app config
- Add a provider entry in app-config.yaml
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
- Register the backend module in packages backend src index ts
// 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
- Register the provider with the catalog builder in packages backend src plugins catalog ts
// 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.
- Add the API Docs page route in packages app src App tsx
// 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
Set up Backstage in minutes with Roadie
Focus on using Backstage, rather than building and maintaining it.