Structuring the Service Catalog in Spotify's Backstage

Backstage’s catalog connects software to its owners and the APIs it exposes. If you are new to the platform, start with why use Backstage.

Choose the entity types

Represent a deployable service as a Component, its interface as an API, and its owning team as a Group. A System groups related software. A team is not itself a service.

Make ownership explicit

Set spec.owner to the owning group. A repository’s CODEOWNERS file does not automatically populate that field in an ordinary catalog descriptor; any synchronization needs to be configured separately.

A complete catalog example

Save these four entities in catalog-info.yaml. The references use the default namespace and point to entities included in the example.

apiVersion: backstage.io/v1alpha1
kind: Group
metadata:
  name: platform-team
spec:
  type: team
  children: []
---
apiVersion: backstage.io/v1alpha1
kind: System
metadata:
  name: customer-platform
spec:
  owner: group:default/platform-team
---
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: customer-service
  description: Service providing the customer API
spec:
  type: service
  lifecycle: production
  owner: group:default/platform-team
  system: customer-platform
  providesApis:
    - customer-api
---
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: customer-api
spec:
  type: openapi
  lifecycle: production
  owner: group:default/platform-team
  system: customer-platform
  definition: |
    openapi: 3.0.3
    info:
      title: Customer API
      version: 1.0.0
    paths:
      /customers:
        get:
          responses:
            '200':
              description: Customer list returned successfully

Register the file through your Backstage instance’s catalog import flow. Its configured location rules must allow these entity kinds. The example API definition documents a response; it does not create or deploy an endpoint.

Use the catalog entity specification when extending the file, and the system model when deciding how to group your software.