How to Guides
Add Your Zuplo API to Backstage
In this guide, we'll walk you through the steps to add a your Zuplo API to Backstage.
1/ Add the OpenAPI Spec Handler#
Backstage allows you to document
API entities
using an OpenAPI file. Although Zuplo is OpenAPI based, you cannot directly use
your routes.oas.json
file, as it is missing details about your API. Instead,
you will need to use the public-ready version of your spec, by adding an
OpenAPI Spec Handler.
Add a new route with the path /openapi
, and select the OpenAPI Spec Handler
from the Request Handler selector. Save your changes and commit them to your
production branch. If you haven't already connected your Zuplo API to a GitHub
repository, you can follow
these instructions to do so. Once your
Zuplo API is redeployed, you should now be able to retrieve your public-ready
OpenAPI file by hitting https://<your-prod-zuplo-api-domain>/openapi
.
2/ Add Zuplo to your reading.allowed
list#
Navigate to the app-config.yaml
file in your backstage repository. You will
need to allow backstage to call Zuplo's domain to fetch the OpenAPI file. Add
the following code:
backend: reading: allow: - host: "*.zuplo.dev" - host: "*.zuplo.app"
If you are using a custom domain on your Zuplo API - you will need to add that domain in the list above.
3/ Add your Zuplo API to your Backstage Catalog#
The most direct way to add your Zuplo API to backstage is by adding an entry to
your backstage service's entities.yaml
file.
apiVersion: backstage.io/v1alpha1 kind: API metadata: name: backstage-sample-api # Your API name annotations: # Your github project slug Ex. org/repo-name github.com/project-slug: zuplo-samples/backstage-sample-api spec: type: openapi lifecycle: experimental # Change to match your backstage project owner: guests # Change to match your backstage project system: examples # Change to match your backstage project definition: # Change to match your Zuplo API $text: https://backstage-sample-api-main-821019a.zuplo.app/openapi
Once you've added the API component, you must link it to an existing component. For example, if your website provides APIs, you would add the following
--- apiVersion: backstage.io/v1alpha1 kind: Component metadata: name: example-website spec: type: website lifecycle: experimental owner: guests system: examples providesApis: [backstage-sample-api] # This must match the metadata.name of the entity ---
You should now be able to see your API under the APIs tab in Backstage. If you navigate to your API and click the 'DEFINITION' tab - you can even preview your OpenAPI spec.
Congratulations! You've successfully added your Zuplo API to Backstage. You can repeat the steps above for all of your OpenAPI files.
Optional: Reusing your API across Backstage catalogs#
If you do not wish to directly add your Zuplo API to your backstage
entities.yaml
, you can instead add the entity definition to your Zuplo
repository directly, and sync it with backstage using their github integration.
You will still need to follow steps 1 & 2 from the guide above.
1/ Add catalog-info.yaml
to your Zuplo Repository#
In your Zuplo repository, add a file named catalog-info.yaml
and fill it with
the following
apiVersion: backstage.io/v1alpha1 kind: API metadata: name: backstage-sample-api # Your API name annotations: # Your github project slug Ex. org/repo-name github.com/project-slug: zuplo-samples/backstage-sample-api spec: type: openapi lifecycle: experimental # Change to match your backstage project owner: guests # Change to match your backstage project system: examples # Change to match your backstage project definition: # Change to match your Zuplo API $text: https://backstage-sample-api-main-821019a.zuplo.app/openapi
Save and commit this file.
2/ Add your API Component to Backstage#
You can register existing APIs in your catalog directly from Backstage. Navigate to the APIs tab, and click 'REGISTER EXISTING API'.
When prompted for the component URL, enter the github URL of your
catalog-info.yaml
file (ex.
https://github.com/AdrianMachado/adrian-api/blob/main/catalog-info.yaml).
Complete registration of your API. If you run into issues connecting your repository, see our troubleshooting guide.
3/ Link the API to a component#
You should now be able to see your API under the APIs tab in Backstage. If your API is associated with a another entity, you will need to link to that entity as follows:
apiVersion: backstage.io/v1alpha1 kind: System metadata: name: examples spec: owner: guests --- apiVersion: backstage.io/v1alpha1 kind: Component metadata: name: example-website spec: type: website lifecycle: experimental owner: guests system: examples providesApis: [<YOUR_API_NAME>] # This must match the metadata.name from step 1
Troubleshooting#
I can't connect to Github#
If your repository is not public and you haven't already configured Github
authentication -
follow the Github auth guide.
You will likely want to add sign-in support as a part of your Backstage setup,
to authenticate your users. In your app-config.yaml
add:
auth: allowGuestAccess: true environment: development providers: github: development: clientId: ${GITHUB_CLIENT_ID} clientSecret: ${GITHUB_CLIENT_SECRET} signIn: resolvers: - resolver: emailMatchingUserEntityProfileEmail - resolver: usernameMatchingUserEntityName
Additionally, in your index.ts
file, add the following line before calling
backend.start()
backend.add(import("@backstage/plugin-auth-backend-module-github-provider"));
This is not well documented by Backstage - any issues should be directed to them.
Backstage hosted on Roadie.io#
If you are using a managed version of Backstage from services like Roadie.io - you will need to follow their official docs for OpenAPI. We do not guarantee support for these platforms.