In the world of platform engineering, there’s a growing excitement around the open-source tool Backstage. Developed initially as an internal tool at Spotify, Backstage has been donated to the Cloud Native Computing Foundation (CNCF) and is being adopted by thousands of companies.

Backstage’s primary design goal is to improve internal DevOps processes by providing a unified, centralized system for managing software components. However, the potential applications of Backstage extend beyond this original intent.

One intriguing possibility is the use of Backstage as a catalog for your internal APIs. Below, we’ll dive deeper to explore how to use Backstage to catalog your APIs and consider how this could revolutionize API management within your organization.

Backstage as an API Catalog

Backstage’s software catalog is its core feature, managing entities that describe various software components. This includes APIs, making it a potential tool for cataloging your internal APIs alongside your other services. Before we show sample code to set up Backstage for internal APIs, let’s consider one case study of a development team that is already doing this in practice.

Traveloka’s Use of Backstage

Traveloka, one of the largest online travel companies in Southeast Asia, provides a compelling case study. They use Backstage as a developer portal for APIs hosted on Amazon API Gateway. Before Traveloka implemented Backstage, each service team documented APIs in their own way. As a result, developers lost time going back and forth with service teams to build integrations.

An API portal consolidates API documentation in a central place. There are multiple ways to build an API portal. One option is to integrate solutions like ReadMe with your API gateway. Software as a service (SaaS) solutions like ReadMe let you get started quickly and reduce operational overhead. However, folks who prefer a highly configurable setup or open-source solutions often choose to build their own.

By using Backstage, Traveloka’s developers centralize and standardize API contracts and documentation, helping to accelerate development and avoid bottlenecks. Traveloka chose to host Backstage on a cloud service for its portal, partly because the company was already using Backstage as its developer portal.

How to Start Cataloging APIs With Backstage

In the following section, we’ll walk through the steps to deploy Backstage as an API catalog. This process involves setting up a Backstage app, configuring a cloud storage service as the catalog location, and uploading your API definitions for access through the portal. Let’s dive into the details:

1. Create a Backstage App

First, we need to set up the Backstage application. Start by creating a working directory for the code.

mkdir backstage-api-blog
cd backstage-api-blog

Next, use npm to create the Backstage app. When prompted for the app name, enter api-portal. This process may take a few minutes.

npx @backstage/create-app

Use yarn to run the app.

cd api-portal && yarn dev

Now, you can access your Backstage portal at http://localhost:3000. This is where you’ll be able to view and manage your APIs once they’re uploaded.

After you’ve set up your Backstage app and started it using the command yarn dev, it will be locally hosted on your machine. This means the app is running on your computer and can be accessed through a web browser. The address http://localhost:3000 is the default local network address where your Backstage app can be accessed.

2. Configure Cloud Storage as Catalog Location

After setting up your Backstage app, the next step is to configure a cloud storage service, such as Amazon S3 or Azure Blob Storage, as the catalog location. This involves creating a storage bucket and configuring it to store your API definitions. You’ll need to set up appropriate permissions to ensure your Backstage app can access the storage bucket.

3. Upload API Definition to Cloud Storage and Test Portal

Once your storage bucket is set up, you can upload your API definitions to it. These definitions should be in a format that Backstage can understand, such as YAML or JSON. After uploading the definitions, you can test your portal by navigating to the APIs in the Backstage interface. If everything is set up correctly, you should see your APIs listed in the catalog.

Backstage as a Developer Portal

Backstage’s potential extends beyond cataloging APIs. It could also serve as a developer portal, bridging the gap between API publishers and consumers. Developers can use API contracts and documentation published by producers to build client applications.

Moreover, Backstage integrates with cloud providers and other external systems using plugins. This makes it a highly configurable setup for organizations preferring open-source solutions.

API Governance With Backstage

API governance involves managing and controlling the usage, development, and maintenance of APIs within an organization. It ensures that APIs are developed, deployed, and used in a consistent, secure, and efficient manner.

Backstage can aid API governance by providing a centralized location for API documentation. This can streamline development efforts, enhance security and compliance, and foster collaboration. This could also drive innovation by enabling more seamless integration and interoperability across systems and applications.

Backstage Plugin Marketplace

The Backstage plugin marketplace offers a variety of plugins that can extend Backstage’s functionalities. Here are a few examples that are relevant to API development and operations:

• 3scale by Red Hat: This plugin synchronizes 3scale content into the Backstage catalog, allowing APIs from multiple 3scale tenants to be available in the Backstage catalog.
• API Docs by SDA SE: This plugin provides components to discover and display API entities as an extension to the catalog plugin.
• API Linter by Zalando: API Linter is a quality assurance tool that checks the compliance of API’s specifications to Zalando’s API rules.
• API SDK Generator by Konfig: This plugin generates SDKs for your REST API to accelerate integration.
• API Spectral Linter by dweber019: API Spectral Linter is a quality assurance tool that checks the compliance of API’s specifications Spectral rule sets.
• WSDL/SOAP viewer by dweber019: An API docs extension to render WSDL/SOAP web services in a human-readable manner.
• Apollo Explorer by unredundant: Integrates Apollo Explorer graphs as a tool to browse GraphQL API endpoints inside Backstage.

These plugins, along with many others available in the marketplace, can greatly enhance your API management capabilities with Backstage.

Final Thoughts on Backstage and APIs

Backstage emerges as a highly promising solution for cataloging APIs, serving as a developer portal, and aiding in API governance. Its flexibility and extensibility, coupled with its growing adoption in the tech industry, make it a tool worth considering for organizations seeking to streamline their API management processes. By centralizing API documentation, fostering collaboration among teams, and driving innovation through seamless integration and interoperability across systems and applications, Backstage has the potential to significantly enhance your organization’s API strategy.

As the Backstage community continues to grow and contribute new plugins and features, it’s an exciting time to consider adopting Backstage for your API management needs. Whether you’re a small startup or a large enterprise, Backstage offers solutions that can be tailored to your specific requirements, making it a versatile tool in the ever-evolving landscape of platform engineering.