Demo API Entity

In this guide, we’ll walk through how to define an API entity in Backstage, link it to the component that provides it (the authentication service), and show how another component (e.g., a shopping cart) consumes it. You’ll learn how to embed or reference your OpenAPI spec, configure Backstage to fetch external files, and visualize relationships in the catalog.

1. Import the Existing Authentication Service Component

First, ensure you have already registered your auth-service component in the catalog. This service will expose the API that downstream services use to verify user authentication.

apiVersion: backstage.io/v1beta1
kind: Component
metadata:
  name: auth-service
  description: Authentication service for user login and token management
  tags:
    - javascript
  links:
    - url: https://admin.example.com
      title: Admin Dashboard
      icon: dashboard
      type: admin-dashboard
spec:
  type: service
  lifecycle: production
  owner: guests

2. Define the API Entity

Co-locate the API definition with the component in your catalog-info.yaml. Add the providesApis field to the component, then define a new API entity.

apiVersion: backstage.io/v1beta1
kind: Component
metadata:
  name: auth-service
  description: Authentication service for user login and token management
  tags:
    - javascript
spec:
  type: service
  lifecycle: production
  owner: guests
  providesApis:
    - auth-api
---
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: auth-api
  description: Service API for verifying user authentication status
spec:
  type: openapi
  lifecycle: production
  owner: guests
  apiProvidedBy: auth-service
  # definition goes below

3. Embed or Reference Your OpenAPI Definition

The definition property accepts inline specs or external references. Backstage supports formats such as OpenAPI, AsyncAPI, GraphQL, and gRPC.

3.1 Inline OpenAPI Example

spec:
  type: openapi
  lifecycle: production
  owner: guests
  apiProvidedBy: auth-service
  definition: |
    openapi: "3.0.0"
    info:
      version: 1.0.0
      title: Authentication Service API
      license:
        name: MIT
    servers:
      - url: https://auth.example.com/v1
    paths:
      /signup:
        post:
          summary: Create a new user account
          responses:
            '201':
              description: Created

4. Reference an External OpenAPI Spec

Store your OpenAPI YAML in your repo (e.g., openapi/auth-api-spec.yaml) and reference its raw GitHub URL.

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: auth-api
  description: Service API for verifying user authentication status
spec:
  type: openapi
  lifecycle: production
  owner: guests
  apiProvidedBy: auth-service
  definition:
    $text: https://raw.githubusercontent.com/your-org/backstage-auth-service/main/openapi/auth-api-spec.yaml

5. Configure Backstage to Fetch External Specs

By default, Backstage blocks external hosts. Allow the GitHub raw domain in your backend’s app-config.yaml so the spec can be fetched as plain text.

# app-config.yaml
reading:
  allow:
    - host: 'raw.githubusercontent.com'

6. View the API in Backstage

Navigate to Catalog > Components > auth-service and select the API tab. You should see auth-api listed.

You can also browse Catalog > APIs and select auth-api.

Under Definition, Backstage renders the interactive documentation:

7. Define API Consumers

To show that another service consumes auth-api, update the consuming component’s entity:

apiVersion: backstage.io/v1alpha1
kind: System
metadata:
  name: purchasing
  description: System for managing user purchases
spec:
  owner: ecommerce
  domain: shopping-app
---
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: shopping-cart
  description: Frontend for selecting products and completing purchases
spec:
  type: website
  lifecycle: production
  owner: user:john
  system: purchasing
  dependsOn:
    - component: inventory
  consumesApis:
    - auth-api

Now the shopping-cart component graphically displays its dependency on auth-api in the Backstage catalog.

Backstage Entity Summary

Links and References

• Backstage Catalog Descriptor Format
• Backstage API Docs
• GitHub Raw Content Docs