APIs

Summary

An API describes an interface that can be exposed by a component. The API can be defined in different formats, like OpenAPI, AsyncAPI, GraphQL, gRPC, or other formats. See common api types for an exhaustive list of supported formats.

Definition

Backstage Docs

See the backstage docs for a full description of the API entity definition.

As with all other entities, an API consists of the envelope types, apiVersion and kind, as well as generic metadata and a specific spec.

apiVersion [Required]

The apiVersion is the version of specification format for that particular entity that the specification is made against. The version is used for being able to evolve the format and to distinguish them from other types of object that share the same type of structure - e.g. Kubernetes object manifests.

At present all entity descriptors should be given an apiVersion of backstage.io/v1alpha1. This will change as backstage develops or if we choose to add custom entity kinds to the portal.

kind [Required]

The kind is the high level entity type being described. For an API this must be API, e.g. kind: API.

Other available kinds are enumerated in the entity types reference.

metadata [Required]

A structure that contains metadata about the entity, i.e. things that aren't directly part of the entity specification itself. See the entity metadata reference for more details about this structure.

name [Required]

The name of the entity. This name is both meant for human eyes to recognize the entity, and for machines and other components to reference the entity, e.g. visits-tracking-service

Names must be unique per kind, at any point in time. This uniqueness constraint is case insensitive. Names may be reused at a later time, after an entity is deleted from the registry.

Names are required to follow a certain format. Entities that do not follow those rules will not be accepted for registration in the catalog. The required format is as follows:

• Strings of length at least 1, and at most 63
• Must consist of sequences of [a-z0-9A-Z] possibly separated by one of [-_.]

title [Optional]

A display name of the entity, to be presented in user interfaces instead of the name property above, when available.

This field is sometimes useful when the name is cumbersome or ends up being perceived as overly technical. The title generally does not have as stringent format requirements on it, so it may contain special characters and be more explanatory. Do keep it very short though, and avoid situations where a title can be confused with the name of another entity, or where two entities share a title.

Note that this is only for display purposes, and may be ignored by some parts of the code. Entity references still always make use of the name property for example, not the title.

description [Optional]

A human readable description of the entity, to be shown in the developer portal. Should be kept short and informative, suitable to give an overview of the entity's purpose at a glance. More detailed explanations and documentation should be placed elsewhere.

labels [Optional]

Labels are optional key/value pairs of that are attached to the entity, and their use is identical to Kubernetes object labels.

Their main purpose is for references to other entities, and for information that is in one way or another classifying for the current entity. They are often used as values in queries or filters.

Both the key and the value are strings, subject to the following restrictions.

Keys have an optional prefix followed by a slash, and then the name part which is required. The prefix, if present, must be a valid lowercase domain name, at most 253 characters in total. The name part must be sequences of [a-zA-Z0-9] separated by any of [-_.], at most 63 characters in total.

The backstage.io/ prefix is reserved for use by Backstage core components.

Values are strings that follow the same restrictions as name above.

annotations [Optional]

An object with arbitrary non-identifying metadata attached to the entity, identical in use to Kubernetes object annotations.

Their purpose is mainly, but not limited, to reference into external systems. This could for example be a reference to the git ref the entity was ingested from, to monitoring and logging systems, to PagerDuty schedules, etc. Users may add these to descriptor YAML files, but in addition to this automated systems may also add annotations, either during ingestion into the catalog, or at a later time.

Both the key and the value are strings, subject to the following restrictions.

Keys have an optional prefix followed by a slash, and then the name part which is required. The prefix must be a valid lowercase domain name if specified, at most 253 characters in total. The name part must be sequences of [a-zA-Z0-9] separated by any of [-_.], at most 63 characters in total.

The backstage.io/ prefix is reserved for use by Backstage core components.

Values can be of any length, but are limited to being strings.

tags [Optional]

A list of single-valued strings, for example to classify catalog entities in various ways. This is different to the labels in metadata, as labels are key-value pairs.

The values are user defined, for example the programming language used for the component, like java or go.

This field is optional, and currently has no special semantics.

Each tag must be sequences of [a-z0-9] separated by -, at most 63 characters in total.

links [Optional]

A list of external hyperlinks related to the entity. Links can provide additional contextual information that may be located outside of the developer portal itself. For example, an admin dashboard or external CMS page.

Users may add links to descriptor YAML files to provide additional reference information to external content & resources. Links are not intended to drive any additional functionality within Backstage, which is best left to annotations and labels. It is recommended to use links only when an equivalent well-known annotation does not cover a similar use case.

Fields of a link are:

url [Required]

A url in a standard uri format, e.g. url: https://example.com/some/page

title [Optioanl]

A user friendly display name for the link, e.g. title: Example Website

icon [Optional]

A key representing a visual icon to be displayed in the UI, e.g. icon: docs

The icon field value is meant to be a semantic key that will map to a specific icon that may be provided by an icon library (e.g. material-ui icons). These keys should be a sequence of [a-z0-9A-Z], possibly separated by one of [-_.]. The default backstage icon-component mappings are used, see the app-defaults for details. A generic fallback icon would be provided if a mapping cannot be resolved.

spec [Required]

The actual specification data that describes the entity.

type [Required]

The type of API as a string, e.g. type: openapi.

Whilst the spec.type of a API may be any string, visualisation is only available for a small subset. Further to this, understanding is made easier by sticking to a small set of well-known and common values. Thus we recommend that when specifying an API one of the following is used in this field:

• 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

lifecycle [Required]

The lifecycle state of the API as a string, e.g. lifecycle: production.

Whilst the spec.type of a Component or API may be any string, understanding is made easier by sticking to a small set of well-known and common values. Thus we recommend that when specifying an entity one of the following is used in this field:

• experimental - an experiment or early, non-production entity, signaling that users may not prefer to consume it over other more established entities, or that there are low or no reliability guarantees
• production - an established, owned, maintained entity
• deprecated - an entity that is at the end of its lifecycle, and may disappear at a later point in time

owner [Required]

An entity reference to the owner of the entity, e.g. owner: user:enu43627. Users and Groups are automatically populated, and can listed in the catalog by filtering by Kind of User or Group respectively.

The owner of an entity is the group or user that bears ultimate responsibility for the entity, and has the authority and capability to develop and maintain it. They will be the point of contact if something goes wrong, or if features are to be requested. The main purpose of this field is for display purposes in Backstage, so that people looking at catalog items can get an understanding of to whom this entity belongs. It is not to be used by automated processes to for example assign authorization in runtime systems. There may be others that also develop or otherwise touch the entity, but there will always be one ultimate owner.

system [Optional]

An entity reference to the System that the entity belongs to, e.g. developer-portal. There is no requirement for this System to be created within the same location; Existing Systems can be listed in the catalog by filtering by Kind of System.

definition [Required]

The definition of the API, as a multi-line string, based on the format defined by type.

For example, where type is openapi:

definition: |
  openapi: 3.0.0
  info:
    title: Backstage API
    version: 0.0.1

Tip

The API schema can be located in another file and imported by using substitutions, e.g.:

definition:
    $text: ./schema-file.json

$text, $json & $yaml are available, for more details see the backstage docs