Skip to main content

API Spec Refernces

Here’s a guideline to add API specifications to your IDP based on the Backstage descriptor format.

Descriptor File Structure

1. File Naming:

Typically named catalog-info.yaml or idp.yaml.

2. Format:


3. Sections:

Envelope, Metadata, API Specification, Relations, Status.

Defining an API Entity

1. apiVersion:

Specify the API version, e.g.,

2. kind:

This should be API.

3. metadata:

Includes name, description, labels, and annotations.

4. name:

Unique identifier for the API.

5. description:

Brief overview of the API.

6. labels/annotations:

Key-value pairs for additional metadata.

API Specification

1. spec:

Contains the actual API specification details.

2. type:

The type of API (e.g., openapi, grpc), the current set of well-known and supported values for this field is:

openapi - An API definition in YAML or JSON format based on the OpenAPI version 2 or version 3 spec.

asyncapi - An API definition based on the AsyncAPI spec.

graphql - An API definition based on GraphQL schemas for consuming GraphQL based APIs.

grpc - An API definition based on Protocol Buffers to use with gRPC.

3. lifecycle:

Stage of the API lifecycle (e.g., production, experimental).

4. owner:

Team or individual responsible for the API.

5. definition:

Location of the API definition file (e.g., a URL to a Swagger file).

Substitutions in Descriptor

  1. Supports $text, $json, $yaml for embedding external content.
  2. Useful for loading API definitions from external sources.


kind: API
name: petstore
description: The petstore API
- store
- rest
- url:
title: GitHub Repo
icon: github
- url:
title: API Spec
icon: code
type: openapi
lifecycle: dev
owner: Harness_Partners
$text: ./petstore.oas.yaml