About this guide
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.
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.
In this step, you will use our template GitHub repository to set up an API definition project.
- Log into GitHub and access the Redocly openapi-starter repository.
- On the repository page, select Use this template. This opens the dialog to create a new repository from the template.
- 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.
- Select Create repository from template to complete the action and exit the dialog.
You should now be able to access your newly created repository. An example API definition called
openapi.yaml is in the
In this step, you will connect your new repository to the API registry and add the example API definition.
- Log into Redocly Workflows and access the API registry page.
- On the API registry page, select Add API.
- 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.
- In the Choose source step, choose GitHub (recommended) and select Next.
- 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.
- In the Version name step, set a custom name for the API version and select Finish to close the dialog.
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.
In this step, you will check the validation status of your API definition in the API registry, and start a new build.
- 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.
- 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.
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.
- To start a new build and validate the API definition again, select Restart (2).
You have successfully added an API definition to the API registry and validated it.