API-Driven Service Catalogs: CNPA practice questions

A service catalog answers two questions for an engineering organization: what software and capabilities exist, and who owns them. An API-driven catalog stores that information as machine-readable data that tools can query and update, instead of a spreadsheet or wiki page that goes stale. In platform engineering the term covers two related things: a catalog of the software the organization runs, and a catalog of the capabilities the platform offers, each backed by an API.

Backstage's Software Catalog is the usual reference for the first. It is a centralized system that keeps track of ownership and metadata for services, websites, libraries, data pipelines, ML models and more. Its source of truth is metadata YAML files stored with the code in source control, which Backstage harvests and visualizes; the descriptor format documentation recommends naming them catalog-info.yaml, and they usually sit in the repository root. Components can be registered manually, created through Backstage templates, or imported by integrating an external source. The catalog's system model has three core entities: components are individual pieces of software, APIs are the boundaries between components, and resources are the physical or virtual infrastructure a component needs to operate, such as databases, topics, buckets or CDNs. Components declare the APIs they provide and consume, and API entities can carry definitions in formats such as OpenAPI, AsyncAPI, GraphQL or gRPC, so consumers can find and read them. User and Group entities record people and teams, which is how ownership is expressed.

For the second meaning, the platform's own APIs act as the catalog of capabilities. In a Kubernetes-based platform each capability can be a custom resource type, so the set of resource types the platform exposes is effectively its menu. The Platforms White Paper describes its portal capability as publishing documentation, service catalogs and project templates, and the maturity model's integrated level includes a scenario in which a user selects Provision a Database from a catalog in a portal, and automation creates the database and sends back a URL and a location for the credentials. The catalog entry is the front; the API behind it does the provisioning.

Why it matters: ownership data turns incident routing, audits and migrations into lookups, which the Backstage documentation describes as no more orphan software hiding in the dark corners of the ecosystem. Machine-readable descriptors also let tooling report which services lack an owner, documentation or an API definition.

Misconceptions are that a catalog must be filled in by hand in a central tool (descriptors kept next to the code stay current through normal reviews), that the catalog is the platform (it is one interface onto it), and that a catalog only covers microservices.

At associate level, expect questions about what a catalog records, where its data should live, how components, APIs and resources relate, and how a catalog entry connects to self-service provisioning.