DEV Community

Preecha
Preecha

Posted on

Backstage Developer Portal: Complete Guide & Best Practices

The Backstage developer portal is an open-source platform originally created by Spotify to help engineering teams discover, document, manage, and operate software components, APIs, services, and infrastructure from one interface.

Try Apidog today

As organizations scale, services multiply, ownership becomes harder to track, and documentation often ends up scattered across wikis, repositories, Slack threads, and spreadsheets. Backstage addresses this by giving teams a central, customizable developer portal for visibility, discoverability, and self-service workflows.

Why Backstage Matters for Platform Engineering

A Backstage developer portal is more than an internal wiki. It is usually used as the front door to an engineering platform.

Backstage helps teams:

  • Centralize documentation, API specs, ownership, and infrastructure links
  • Improve developer experience by reducing tool-hopping and search time
  • Enable self-service workflows for creating services, APIs, and infrastructure
  • Standardize new projects with templates and guardrails
  • Scale service discovery across many teams and microservices

For platform engineering teams, Backstage becomes the place where developers answer questions like:

  • Who owns this service?
  • Where is the API documentation?
  • How do I create a new service?
  • What dependencies does this component have?
  • Where are the runbooks, dashboards, and deployment links?

Core Backstage Features You Should Implement First

Backstage is highly extensible, but most teams should start with a few foundational capabilities.

1. Software Catalog

The Software Catalog is the core of Backstage. It acts as an inventory of services, APIs, libraries, websites, data pipelines, and other software assets.

A typical catalog entry includes:

  • Component name
  • Owner
  • Description
  • Repository link
  • Documentation link
  • System or domain
  • Related APIs
  • Lifecycle status
  • Dependencies

A minimal catalog-info.yaml file might look like this:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment-service
  description: Handles payment authorization and transaction processing
  annotations:
    github.com/project-slug: example-org/payment-service
spec:
  type: service
  lifecycle: production
  owner: payments-team
  system: checkout-platform
Enter fullscreen mode Exit fullscreen mode

Once this file is added to a repository and registered in Backstage, developers can discover the service, identify the owning team, and navigate to related resources.

Practical setup steps

  1. Identify your most important services and APIs.
  2. Add a catalog-info.yaml file to each repository.
  3. Define ownership using teams or groups.
  4. Register the catalog files in Backstage.
  5. Make catalog metadata part of your pull request checklist.

Start small. Registering your top 20 production services is often more useful than trying to model the entire organization on day one.

2. API Management and Discovery

Backstage can display API definitions such as OpenAPI, Swagger, GraphQL, and AsyncAPI specs. This makes API discovery easier because API documentation lives next to ownership, source code, and service metadata.

A simple API entity can be registered like this:

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: payment-api
  description: Public API for payment authorization
spec:
  type: openapi
  lifecycle: production
  owner: payments-team
  definition:
    $text: https://example.com/openapi/payment-api.yaml
Enter fullscreen mode Exit fullscreen mode

You can also link an API to a service component:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment-service
  description: Handles payment authorization and transaction processing
spec:
  type: service
  lifecycle: production
  owner: payments-team
  system: checkout-platform
  providesApis:
    - payment-api
Enter fullscreen mode Exit fullscreen mode

This allows developers to navigate from a service to the APIs it provides.

Tools like Apidog fit well into this workflow. Teams can design and document APIs in Apidog, export OpenAPI definitions, and surface those definitions in Backstage.

Practical API workflow

  1. Design or document the API in Apidog.
  2. Export or publish the OpenAPI specification.
  3. Register the API in Backstage using an API entity.
  4. Link the API to its owning service with providesApis.
  5. Keep API specs updated as part of the release process.

3. Software Templates

Software Templates let developers create new services, libraries, or infrastructure components through standardized workflows.

Templates are useful when you want every new project to start with:

  • Approved tech stack
  • Repository structure
  • CI/CD pipeline configuration
  • Security checks
  • Observability defaults
  • Documentation boilerplate
  • Ownership metadata
  • Backstage catalog registration

A template can collect user input, create a repository, generate files, and register the component in the catalog.

Example template input fields:

parameters:
  - title: Service information
    required:
      - name
      - owner
    properties:
      name:
        title: Service name
        type: string
        description: Unique name for the new service
      owner:
        title: Owner
        type: string
        description: Team that will own this service
      description:
        title: Description
        type: string
        description: Short explanation of what the service does
Enter fullscreen mode Exit fullscreen mode

Practical template use cases

Create templates for:

  • New backend services
  • New frontend applications
  • New APIs
  • New libraries
  • New infrastructure modules
  • New documentation sites

Templates reduce copy-paste setup work and make best practices the default path.

4. Plugin Ecosystem

Backstage’s plugin ecosystem is one of its biggest strengths. Plugins connect the portal to the tools developers already use.

Common plugin categories include:

  • Source control integrations
  • CI/CD systems such as Jenkins, GitHub Actions, or GitLab CI
  • Kubernetes views
  • Incident management tools such as PagerDuty or Opsgenie
  • API documentation
  • Security and compliance dashboards
  • Monitoring and observability tools
  • Search providers

The goal is not to install every plugin. The goal is to reduce context switching for high-frequency developer tasks.

Practical plugin selection checklist

Before adding a plugin, ask:

  • Does this solve a common developer workflow?
  • Does it reduce time spent switching tools?
  • Does it expose information developers already need?
  • Who will maintain the integration?
  • Is the data reliable enough to show in the portal?

Start with plugins that support ownership, deployments, documentation, incidents, and service health.

5. Search and Discovery

Search is essential once your catalog grows. Developers should be able to find services, APIs, documentation, owners, and repositories without knowing exactly where they live.

Useful searchable entities include:

  • Services
  • APIs
  • Documentation
  • Teams
  • Systems
  • Repositories
  • Runbooks

Backstage helps reduce dependence on tribal knowledge by making engineering assets searchable from one place.

6. Documentation Hub

Backstage treats documentation as a first-class feature through docs-as-code workflows.

Teams can keep documentation close to source code and render it inside the portal. This makes docs easier to update because they follow the same review process as code.

A common repository structure looks like this:

payment-service/
├── catalog-info.yaml
├── docs/
│   ├── index.md
│   ├── architecture.md
│   └── runbook.md
└── mkdocs.yml
Enter fullscreen mode Exit fullscreen mode

Example mkdocs.yml:

site_name: payment-service
nav:
  - Home: index.md
  - Architecture: architecture.md
  - Runbook: runbook.md
plugins:
  - techdocs-core
Enter fullscreen mode Exit fullscreen mode

Practical docs to include

For each production service, aim to include:

  • Overview
  • Architecture notes
  • Local development setup
  • Deployment process
  • Runbook
  • On-call or incident response notes
  • API references
  • Dependencies
  • Ownership and escalation path

Common Backstage Use Cases

Onboarding New Developers

Backstage improves onboarding by giving new engineers one place to find services, APIs, teams, and documentation.

A practical onboarding flow might include:

  1. New developer opens Backstage.
  2. They browse their team’s owned services.
  3. They read service docs and runbooks.
  4. They inspect dependencies and APIs.
  5. They use templates to create a sample service.
  6. They follow links to repositories, dashboards, and CI/CD pipelines.

This reduces the need to ask basic discovery questions in Slack or meetings.

Service Ownership and Accountability

Backstage makes ownership explicit.

A service catalog entry should answer:

  • Who owns this service?
  • Is it production or experimental?
  • What system does it belong to?
  • What APIs does it provide?
  • Where is the source code?
  • Where are the docs?
  • Where are dashboards and runbooks?

This helps avoid orphaned services and makes incident routing easier.

API Design and Documentation

For API-heavy organizations, Backstage is useful when API specs are connected to services and teams.

A practical flow with Apidog and Backstage:

  1. Design and document the API in Apidog.
  2. Export or publish the OpenAPI definition.
  3. Register the API in Backstage.
  4. Link it to the service that owns it.
  5. Make the API searchable in the portal.

This gives API consumers a single place to find the API contract, owner, and related service context.

Self-Service Infrastructure

Backstage can expose self-service actions through templates and plugins.

Examples include:

  • Create a new service repository
  • Generate a new API project
  • Provision infrastructure
  • Register a service in the catalog
  • Create documentation scaffolding
  • Trigger deployment workflows

Self-service reduces ticket queues and lets platform teams encode approved workflows into reusable templates.

Engineering Standards and Scorecards

Backstage can also help teams track engineering standards.

Examples of useful checks:

  • Does the service have an owner?
  • Does it have documentation?
  • Does it define a lifecycle?
  • Does it have a runbook?
  • Does it expose API specs?
  • Does it meet security requirements?
  • Does it have CI/CD configured?

Scorecards and quality dashboards can make these standards visible without relying on manual audits.

How to Set Up a Backstage Developer Portal

Step 1: Define Your Catalog Model

Before installing plugins or building templates, decide how you want to model your organization.

Define:

  • Components
  • APIs
  • Systems
  • Domains
  • Groups
  • Users
  • Resources

Example relationship:

Domain: Payments
└── System: Checkout Platform
    ├── Component: payment-service
    ├── Component: fraud-check-service
    └── API: payment-api
Enter fullscreen mode Exit fullscreen mode

Keep the model simple at first. You can refine it later.

Step 2: Register Your First Services

Start with a small set of important services.

For each service:

  1. Add catalog-info.yaml.
  2. Define the owner.
  3. Add lifecycle status.
  4. Link source code.
  5. Add docs.
  6. Register the file in Backstage.

Example:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: fraud-check-service
  description: Evaluates payment risk before authorization
  links:
    - url: https://example.com/dashboards/fraud-check-service
      title: Service dashboard
spec:
  type: service
  lifecycle: production
  owner: risk-team
  system: checkout-platform
Enter fullscreen mode Exit fullscreen mode

Step 3: Add API Specs

For each API, create an API entity and link it to the owning service.

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: fraud-check-api
  description: API for payment risk evaluation
spec:
  type: openapi
  lifecycle: production
  owner: risk-team
  definition:
    $text: https://example.com/openapi/fraud-check-api.yaml
Enter fullscreen mode Exit fullscreen mode

Then link it from the service:

spec:
  providesApis:
    - fraud-check-api
Enter fullscreen mode Exit fullscreen mode

Step 4: Add Documentation

Use docs-as-code so documentation is versioned and reviewed with the service.

Minimum recommended docs:

docs/
├── index.md
├── getting-started.md
├── architecture.md
├── runbook.md
└── api.md
Enter fullscreen mode Exit fullscreen mode

Make documentation ownership part of service ownership.

Step 5: Create Your First Template

Start with one high-value template, such as “Create a new backend service.”

The template should generate:

  • Repository structure
  • Backstage catalog file
  • README
  • CI/CD config
  • Basic docs
  • Example health check
  • Ownership metadata

This makes standardization automatic.

Step 6: Add Plugins Based on Developer Workflows

Add plugins based on actual developer needs.

Good early plugin targets:

  • Source control
  • CI/CD
  • Kubernetes
  • Documentation
  • Search
  • Incident management
  • API documentation

Avoid turning Backstage into a link dump. Each plugin should support a workflow.

Best Practices for Backstage Adoption

Start with Ownership

Backstage becomes useful when ownership is accurate. Make sure every production component has an owner.

Bad:

owner: unknown
Enter fullscreen mode Exit fullscreen mode

Better:

owner: payments-team
Enter fullscreen mode Exit fullscreen mode

Make Metadata Part of the Development Workflow

Add catalog metadata requirements to pull request reviews.

For new services, require:

  • catalog-info.yaml
  • Owner
  • Lifecycle
  • Description
  • Documentation
  • API references, if applicable

Keep the Catalog Fresh

A stale catalog reduces trust. Automate validation where possible.

Useful checks:

  • Catalog file exists
  • Owner exists
  • Links are valid
  • API specs are reachable
  • Documentation builds successfully

Use Templates to Enforce Standards

Instead of asking teams to remember every best practice, encode standards into templates.

Use templates for:

  • Service creation
  • API scaffolding
  • Documentation setup
  • Infrastructure provisioning
  • Repository initialization

Prioritize Developer Experience

Backstage should make developers faster, not add another administrative task.

Focus on:

  • Fast search
  • Clear ownership
  • Useful docs
  • Reliable links
  • Self-service actions
  • Minimal manual metadata

Integrating Apidog with Backstage

A practical Backstage and Apidog workflow looks like this:

  1. Design and test APIs in Apidog.
  2. Export or publish the OpenAPI specification.
  3. Register the API in Backstage as an API entity.
  4. Link the API to the service that provides it.
  5. Use Backstage search to make the API discoverable across teams.

Example Backstage API registration:

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: user-profile-api
  description: API for user profile management
spec:
  type: openapi
  lifecycle: production
  owner: identity-team
  definition:
    $text: https://example.com/openapi/user-profile-api.yaml
Enter fullscreen mode Exit fullscreen mode

Example service relationship:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: user-profile-service
  description: Stores and manages user profile data
spec:
  type: service
  lifecycle: production
  owner: identity-team
  providesApis:
    - user-profile-api
Enter fullscreen mode Exit fullscreen mode

This setup helps developers discover APIs in context: who owns them, which service provides them, and where the API contract lives.

Real-World Example: Wise and Backstage

Wise adopted Backstage to address issues such as documentation quality, discoverability, and engineering cognitive load.

With Backstage, organizations like Wise can centralize:

  • Service and API documentation
  • Ownership mappings
  • Team information
  • Self-service templates
  • Engineering standards

The result is a developer portal that helps engineers find what they need faster and follow standardized workflows when creating or operating services.

Frequently Asked Questions

What types of organizations benefit most from Backstage?

Backstage is most useful for organizations with multiple services, APIs, repositories, or engineering teams.

It is especially helpful when teams struggle with:

  • Documentation sprawl
  • Unclear ownership
  • Slow onboarding
  • Repeated setup work
  • Manual platform requests
  • Poor service discoverability

Is Backstage open source?

Yes. Backstage is open source under the Apache 2.0 license.

There are also managed and commercial offerings, such as Spotify Portal and Roadie, for teams that prefer hosted solutions.

Can Backstage be customized?

Yes. Backstage is highly extensible through plugins, themes, templates, and custom workflows.

Teams commonly customize:

  • Navigation
  • Homepage layout
  • Entity pages
  • Software templates
  • Plugins
  • Branding
  • Search integrations

How does Backstage relate to API management?

Backstage is not a full API gateway or runtime API management platform. Its strength is API discoverability and documentation.

It helps teams:

  • Register APIs
  • Display API specs
  • Link APIs to owning services
  • Show ownership and lifecycle
  • Make APIs searchable

When combined with API design and documentation tools like Apidog, Backstage can become the central place where developers discover and understand internal APIs.

Conclusion

Backstage gives engineering teams a practical way to centralize service ownership, documentation, APIs, templates, and operational tooling.

To implement it effectively:

  1. Start with the Software Catalog.
  2. Register your most important services.
  3. Add ownership and lifecycle metadata.
  4. Connect API specs.
  5. Add docs-as-code.
  6. Build templates for common workflows.
  7. Add plugins only where they improve developer workflows.

Used well, Backstage becomes the front door to your engineering platform: searchable, standardized, and built for developer self-service.

Top comments (0)