APIMatic SDKs in Backstage Developer Portal
Tags: backstage, sdk, documentation, devex
Published: 2024-03-06 01:59:37

By combining APIMatic’s high-quality idiomatic SDKs with the Backstage developer portal, you can create a compelling and differentiated developer experience. 

## What is Backstage?
[Backstage](http://backstage.io) is an open-source platform developed by Spotify for managing the entire lifecycle of developer infrastructure, including services, APIs, documentation, and more. Backstage streamlines the development process through its centralized and customizable platform, offering a unified dashboard that consolidates information on projects, services, and infrastructure. Acting as a service catalog enhances transparency by allowing teams to document and discover internal services easily. Backstage's extensible architecture supports a robust plugin ecosystem, enabling teams to tailor the platform to their specific workflows and preferences. The platform promotes collaboration, accelerates onboarding through standardized documentation, and integrates seamlessly with various DevOps tools.

## Extending Backstage with SDKs
As the number of services and API complexity grows, teams using Backstage as their developer portal may look to add SDKs to support developers in multiple languages. SDKs include code libraries, documentation, getting-started guides, and code samples, empowering developers to interact seamlessly with APIs and services.

APIMatic automates the creation and maintenance of SDKs in various programming languages. In this tutorial, we’ll show you how to take your API developer experience to the next level by using APIMatic to generate SDKs and incorporate them into your Backstage portal.

APIMatic goes above and beyond to ensure a good developer experience by providing auto-generated SDKs in the programming languages you need and includes SDK documentation with guided walkthroughs, code samples, and getting started guides.

We can integrate APIMatic SDKs by incorporating them into a dedicated SDKs page within existing documentation or by embedding the SDKs documentation as a newly registered component in the Backstage portal. In the upcoming sections, we will explore both options to see how they can improve the developer experience within the backstage portal.

## Generate SDKs and Documentation with APIMatic
In this section, we walk through publishing an API portal for APIMatic SDKs. If you already have a generated portal with APIMatic, skip to [Integrate APIMatic with Backstage](#integrate-apimatic-with-backstage) section.

[Start your free trial](https://hubl.li/Q02njtD-0) with access to all SDK generation features.

### Import an API definition
Follow these [instructions](https://docs.apimatic.io/getting-started/importing-api-spec/) to import your existing API definition or use the example [Petstore API](https://gist.github.com/MaryamAdnan3/14186c9c1b0ac5d84b4f48368c7289f1).

<img src="https://www.apimatic.io/hubfs/image-01.png" width="512" height="353" loading="lazy" alt="import OpenAPI definition into APIMatic" style="height: auto; max-width: 100%; width: 512px; margin-left: auto; margin-right: auto; display: block;">

### Generate SDK Portal
Follow these instructions to generate a portal for your SDKs using the API definition you just imported. In the last step, you’ll click “Preview API Portal”. A preview of the default landing page of your portal opens up in a new tab on your browser. From here onwards, you can customize your portal's look, feel, and behavior or publish it.

<img src="https://www.apimatic.io/hubfs/image-02-replacement.png" width="1600" height="830" loading="lazy" alt="Generate Petstore Developer Portal" style="height: auto; max-width: 100%; width: 1600px;">

### Publish SDK Portal
Click the Publish Portal button at the bottom of the page and follow [these instructions](https://docs.apimatic.io/publish-apis/hosting-your-portal/)  to publish a hosted portal.

Once publishing is complete, visit your unique URL to view your SDK documentation. You can also find the URL in the portal _Settings &gt; Publishing_ section of the portal editor.

## Integrate APIMatic with Backstage

_Note: This guide assumes you already have an API Documentation portal with Backstage. For more details, visit their [site](https://backstage.io/docs/getting-started/)_.

### Create a custom page for SDKs

When completed, your Backstage developer portal will include a custom SDK page.

<img src="https://www.apimatic.io/hubfs/image-3-replacement.png" width="1882" height="905" loading="lazy" alt="Custom SDK page in backstage developer portal" style="height: auto; max-width: 100%; width: 1882px;">

After setting up the Backstage platform by following their [getting started guide](https://backstage.io/docs/getting-started/) you’ll see your instance running at http://localhost:3000/. Before running the application, ensure that the tech docs configuration section in 
`app-config.yaml` is configured to run locally.

The first step is to create a customized page in the Backstage platform. The page will include a list of all the supported language SDKs and links to setup instructions.

1. For an overview on the docs-like code solution provided by Backstage, which is responsible for rendering documentation via markdown files, consult the [TechDocs](https://backstage.io/docs/features/techdocs/) documentation.

2. Create a markdown file in your application’s doc folder, which you’ll find at **&lt;root folder/docs&gt;**, and provide a descriptive name **&lt;doc name&gt;.md**.

3. We’ve created a markdown template. Copy the [markdown from here](https://gist.github.com/SidneyAllen/d856f3ef8ac925118bf3ce3f16980aa6#file-sdks-markdown-raw) and paste it into your markdown file. Note the text is for our Petstore example, so you can customize the text for your API. You must replace the YOUR_DOCS_SLUG and YOUR_API_KEY placeholders with the actual values for your SDK documentation. Detailed instructions are below.

4. YOUR_URL_SLUG represents the slug you defined when publishing your APIMatic Portal. To locate this value, hover over the top left corner of your API definition tile in the APIMatic Dashboard and copy the link. You will just need the subdomain of this URL e.g. https://YOUR_DOCS_SLUG.apimatic.dev. Replace all instances of YOUR_DOCS_SLUG with this value. 

<img src="https://www.apimatic.io/hubfs/image-04.png" width="474" height="512" loading="lazy" alt="Publish Petstore developer portal with APIMatic" style="height: auto; max-width: 100%; width: 474px; margin-left: auto; margin-right: auto; display: block;">

5.YOUR_API_KEY represents a unique identifier for your SDK documentation. To access the API Key for your SDK documentation, click the kebab menu (three vertical dots) on the API definition tile to retrieve the API integration key.

6. From the context menu, select ‘API Integration Keys’.

<img src="https://www.apimatic.io/hubfs/image-05.png" width="488" height="512" loading="lazy" alt="API keys for APIMatic Developer Portal" style="height: auto; max-width: 100%; width: 488px; margin-left: auto; margin-right: auto; display: block;">

7. Copy the property titled API KEY. In the markdown template, replace all instances of YOUR_API_KEY with this value.

This concludes your setup for this custom page. Your new page lists all your SDKs. You can save your changes and proceed to the next step.

### Create a link to the custom SDK page

1. Create a `mkdocs.yaml` file in your application’s root folder and change it to reference the markdown document in the navigation bar.

{% gist https://gist.github.com/SidneyAllen/fd3e97e4395c1faf3cf6b8fa1ba6d3b3 %}

2. After running the application successfully, select **Create** from the navigation bar and press the **REGISTER AN EXISTING COMPONENT** button.

<img src="https://www.apimatic.io/hubfs/image-06-replacement.png" width="1915" height="867" loading="lazy" alt="Register an existing component in Backstage developer portal" style="height: auto; max-width: 100%; width: 1915px;">

3. Import the `catalog-info.yaml` file and analyze it on the next page. The catalog-info.yaml file analysis will reveal any problems. Please take care of them before proceeding. You can read more about it [here](https://backstage.io/docs/features/techdocs/creating-and-publishing).

4. Provided the previous steps executed smoothly, you will see the **VIEW THE COMPONENT** button. Pressing this button takes you to a page with the newly created component details. Click on the **DOCS** tab to view the linked SDK documentation.

<img src="https://www.apimatic.io/hubfs/image-07-replacement.png" width="1882" height="903" loading="lazy" alt="image-07-replacement" style="height: auto; max-width: 100%; width: 1882px;">

## Embed APIMatic’s SDK Documentation in Backstage (Optional)
_This section is optional because your SDK documentation is already published and publicly accessible; embedding it in your Backstage portal is a nice touch but not a requirement._

In the previous section, we created a page that redirects to the SDK documentation hosted by APIMatic. We can go further and embed the SDK documentation inside a Backstage portal, and it would look like the following.

<img src="https://www.apimatic.io/hubfs/image-08-replacement.png" width="1888" height="891" loading="lazy" alt="Customize homepage tile in Backstage developer portal" style="height: auto; max-width: 100%; width: 1888px;">

### Generate an APIMatic embed script
APIMatic’s SDK Documentation can be embedded in any web page via an embeddable script. To generate the embed script for your APIMatic docs:

1. Navigate to the APIMatic dashboard.
2. Locate your API definition tile.
3. Click Edit Docs to navigate to the Portal Editor.
<img src="https://www.apimatic.io/hubfs/image-09.png" width="459" height="512" loading="lazy" alt="Edit OpenAPI doc in APIMatic" style="height: auto; max-width: 100%; width: 459px; margin-left: auto; margin-right: auto; display: block;">
4. In the top left corner of the Portal Editor, click the ‘Publish Portal’ button.
5. Choose the _Update Embedded_ option on the next screen.<img src="https://www.apimatic.io/hubfs/image-10.png" width="474" height="512" loading="lazy" alt="Generate embed code for APIMatic developer portal" style="height: auto; max-width: 100%; width: 474px; margin-left: auto; margin-right: auto; display: block;">
6. Select the API version you want to generate the embed script for and click Generate Script.
7. You will be presented with a snippet containing the script. You need to copy this entire script to use in the next section.<img src="https://www.apimatic.io/hubfs/image-11.png" width="495" height="512" loading="lazy" alt="Embed Javascript for Developer Portal" style="height: auto; max-width: 100%; width: 495px; margin-left: auto; margin-right: auto; display: block;">

### Add Embed Script to Backstage Portal
In the previous steps, we used APIMatic to create an embed script. Now include it in the Backstage portal.

First, we’ll create a customized page called SDKs that is accessible from the portal's landing page. This new page displays our embedded portal links to the SDKs.

To achieve this please follow the instructions given in the Backstage official documentation of customizing the home page.

1. We are modifying the default behavior of the application’s home page to link the SDK documentation. Create a new file `HomePage.tsx`. This is where our new homepage component will live. It will look like the following:

{% gist https://gist.github.com/SidneyAllen/264c185fb55344fa1e1e6f3597170fe5 %}

2. Now create a component with the name `ApimaticWidget.tsx` in the components folder of the Backstage application apps folder. This component will load the embedded portal by calling the _initializeWidget_ method. The method uses the script copied earlier in the [previous section](#add-embed-script-to-backstage-portal).

{% gist https://gist.github.com/SidneyAllen/72bf2253fec327d28d54daf897c6374c %}

3. To make the portal accessible through an engaging information card, we will create another component with the name `InformationCard.tsx`.

{% gist https://gist.github.com/SidneyAllen/7d2c7881223fa283330e0c66bff90e1c %}

4. Finally, let's add the routes to the `ApimaticWidget` component in `App.tsx` to make the customized SDK page accessible from the navigation bar.

{% gist https://gist.github.com/SidneyAllen/085cf1f3be392b912f871b8817085342 %}

Now we have achieved an interactive and convenient way of making the SDKs even more accessible for the developers.

<img src="https://www.apimatic.io/hubfs/image-08-replacement.png" width="1888" height="891" loading="lazy" alt="Backstage.io custom tile on Homepage" style="height: auto; max-width: 100%; width: 1888px;">

Clicking on Petstore SDKs takes us right to an embedded APIMatic Portal without leaving our Backstage developer portal.

<img src="https://www.apimatic.io/hubfs/image-14-replacement.png" width="1900" height="901" loading="lazy" alt="APIMatic SDKs embedded in Backstage developer portal" style="height: auto; max-width: 100%; width: 1900px;">

## What’s Next?
In the ever-changing landscape of API-driven development, combining Backstage's API management capabilities with APIMatic's automated SDK generation makes it easy for organizations to establish a strong foundation for API development and consumption.

If you liked what you saw in this blog, [Sign up for APIMatic](https://hubl.li/Q02njtD-0) and get started! We would love to see what you build with APIMatic. Tweet your updated Backstage Portals to us at [@APIMatic](https://twitter.com/apimatic) or drop a mention on [Linkedin](https://www.linkedin.com/company/apimatic-limited/mycompany/).