Redocly API registry quickstart guide

About this guide

This quickstart guide is for users who want to try the Redocly API registry in less than 5 minutes.

If you prefer watching a video, here's the link to our API registry tutorial.

To learn more about how the API registry works, start from the Orientation page.

Before you start

Make sure you fulfill the following prerequisites for working with the API registry:

  • Create an account in Redocly Workflows. You can register for an account directly on the Workflows page or by using the invitation link from an existing Workflows user. Depending on the registration method you chose, you will either create a new organization or join an existing one. Your account in the organization must have the permission to add APIs to the registry.
  • Create an account with a version control service provider such as GitHub or GitLab. We recommend GitHub, and we use it in the examples throughout this guide.
attention

You may need to install and configure the Redocly app for your version control service if it has not been done by the Workflows organization owner. Check our source control documentation for instructions.

Step 1 - Set up your API definition project

In this step, you will use our template GitHub repository to set up an API definition project.

  1. Log into GitHub and access the Redocly openapi-starter repository.
  2. On the repository page, select Use this template. This opens the dialog to create a new repository from the template.
  3. In the Create a new repository from... dialog, select your account as the Owner and set a custom name for your repository under Repository name. Choose whether you want the repository to be public or private. Leave the Include all branches checkbox unselected.

Dialog for creating a new repository from template

  1. Select Create repository from template to complete the action and exit the dialog.
success

You should now be able to access your newly created repository. An example API definition called openapi.yaml is in the openapi folder.

Step 2 - Add your API definition to the registry

In this step, you will connect your new repository to the API registry and add the example API definition.

  1. Log into Redocly Workflows and access the API registry page.
  2. On the API registry page, select Add API.

API registry page with the Add API button

  1. The dialog for adding a new API definition opens. In the Definition name step, set a custom name for your API definition and select Next.
  2. In the Choose source step, choose GitHub (recommended) and select Next.

Source selection dialog

  1. In the Source settings step under GitHub organizations, select the GitHub organization associated with your GitHub account. The Redocly app must be installed and configured for this organization.

Under Repositories, select the repository you have created from our template.

Under Source settings, select the main branch. Provide the path to the API definition root file (in our case, it's the openapi/openapi.yaml file) and select Next.

Source configuration dialog

  1. In the Version name step, set a custom name for the API version and select Finish to close the dialog.
success

Your API definition should now be added to the API registry. You will be redirected to the API version Overview page, where the first build will automatically start. The build process validates and bundles your API definition, and produces a snapshot.

Step 3 - Validate your API definition

In this step, you will check the validation status of your API definition in the API registry, and start a new build.

  1. On the Overview page of your API version, find the Logs section. It should contain a single record of your first build. Select this record to view details about the build.
  2. On the log details page, look for validation status messages. If the API definition is valid, there will be no errors or warnings in the build output. You can view the output by selecting Show terminal (3). When the terminal is active, select Show issues to display errors and warnings if there are any.

The log details page for an API definition

Tip

Select Get snapshot (1) to access some handy options, like downloading your API definition snapshot as a JSON or YAML file, copying the direct link to the snapshot, or opening it in a new browser tab.

  1. To start a new build and validate the API definition again, select Restart (2).
Congratulations!

You have successfully added an API definition to the API registry and validated it.

Next steps