Skip to content

Register a Static API

Preface

This how-to will take you through the steps of registering an API with the developer portal using one of the Git discovery locations.

Get a Repository

To begin, you will need to create or clone a repository in or from one of the Git discovery locations, such that they are available to entity ingress.

Discovery Locations

  • github.com/DiamondLightSource
    • Entity descriptors at /catalog-info.yaml
  • gitlab.diamond.ac.uk
    • Entity descriptors at /catalog-info.yaml

Create an Entity Descriptor

Firstly, we must create the entity descriptor file, please reference the Discovery Locations above for the appropriate location - this is typically catalog-info.yaml at the root of the repository.

Entity Definition

To begin, we will specify the apiVersion to be backstage.io/v1alpha1 and the kind as API.

Example

apiVersion: backstage.io/v1alpha1
kind: API

Metadata

Next, we will fill out the metadata, this is common to all entity types. Only the name field is required with numerous other optional fields available. It is recommended that you enter a title and a description. Complete field descriptions are available in the metadata reference.

Example

metadata:
  name: developer-portal-backend-rest
  title: Developer Portal Backend REST API
  description: A RESTful API exposed by the developer portal backend.

API Spec

Finally, we will fill out the API spec. A type, a lifecycle, an owner and a definition with the system field remaining optional. Complete field descriptions are available in the API spec reference.

Example

spec:
  type: service
  lifecycle: experimental
  owner: user:enu43627
  definition: |
    openapi: 3.0.0
      info:
        title: Backstage API
        version: 0.0.1

Schema Generation

It may often be more convenient to link to a generated schema, this can be achieved with use of the $text substituion which points to the URL of a schema definiton. For example, a url of the form https://github.com/DiamondLightSource/<your_repo>/releases/latest/download/<your_schema_file> can be used to load the contents of the <your_schema> artifact from the latest GitHub release.

Example Completed Descriptor

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: developer-portal-backend-rest
  description: A RESTful API exposed by the developer portal backend.
spec:
  type: openapi
  lifecycle: experimental
  owner: user:enu43627
  system: developer-portal
  definition: |
    openapi: 3.0.0
    info:
      title: Backstage API
      version: 0.0.1

Push & Wait

Now we have created our entity decriptor in the form of a catalog-info.yaml we can push it to one of the discovery locations and wait for the developer portal to discover it - be aware that this may take a while depending on the schedule of the discovery provider.