Kind API

The API Entity Kind describes an interface that a component might expose. Depending on the service, these APIs can be expressed in a variety of formats such as OpenAPI, AsyncAPI, GraphQL, gRPC, among others.

Example Descriptor for API Kind

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: sales-invoice-api
  description: Retrieve invoice details
spec:
  type: openapi
  lifecycle: production
  owner: ecommerce-team
  system: ecommerce-website
  definition: |
    openapi: "3.0.0"
    ...

API Kind Structure

• apiVersion and kind [required]:

  • These fields must be set to backstage.io/v1alpha1 and API.

• spec.type [required]:

  • Represents the API definition's format. Example values include "openapi," "asyncapi," "graphql," and "grpc."

• spec.lifecycle [required]:

  • Indicates the lifecycle phase of the API, such as "production" or "experimental."

• spec.owner [required]:

  • An entity reference pointing to the owner of the API. In the T-matic context, the owner is typically the entity responsible for the API's development and maintenance.

• spec.system [optional]:

  • Refers to the system the API is a part of.

• spec.definition [required]:

  • The actual definition of the API, dependent on the format outlined in spec.type.

Notes on Usage

1. The software catalog accepts any value for the type and lifecycle fields, but organizations should establish a clear taxonomy for consistency.

2. The owner field is used mainly for display purposes, giving users a clear idea of the API's responsible team.

3. The system field, although optional, helps in associating the API with a particular system or application.