Configuring the Try it API console
Overview
The API Try it console allows your users to make API calls directly from the API docs.
Requirements
In order to implement the Try It feature (for either reference docs or within the developer portal), you will need to configure your OpenAPI definition for security schemes and servers. Your server must also support CORS requests (or you can use our CORS proxy).
Security schemes
The API Try it console supports the security schemes that are supported by OpenAPI 3.
Servers
OpenAPI 3 allows you to define the servers, including optional server variable objects.
Property | Required for Try it | Description |
---|---|---|
url | Yes | API requests are sent to this URL directly from the browser or via the CORS proxy. |
description | - | If provided, the description is displayed with the URL. |
variables | - | If provided, fields are added to supply values for each server variable defined. |
Handling requests
You can use one of these options to handle requests:
- Directly from the browser (server requires CORS configuration)
- Using a CORS proxy (server does not require CORS configuration)
Directly from the browser
The CORS (Cross-Origin Resource Sharing) protocol allows scripts running in a browser to access resources from a different origin (e.g. a different domain or port). Preventing scripts from accessing external resources is a reasonable security policy.
However in some cases, scripts must be able to access cross-origin resources to successfully complete a request, for example the Try It API console. For users to interact with your APIs through the API console, you must configure your server(s) to accept requests from a URL where your API reference docs are hosted.
Your server(s) must allow cross-origin resource sharing, and respond to the OPTIONS requests sent by the browser when the user works with the API console. The Access-Control-Allow-Origin
header configured on the server tells the browser whether any origins are allowed to access a resource.
Using a CORS proxy
If you cannot configure your server(s) to allow CORS, you can use Redocly's CORS Proxy feature to prevent issues with unsuccessful requests from the API console. When you enable the CORS Proxy feature, all requests sent from the API console are routed through the CORS proxy server. The URL in each request is automatically prepended by the CORS proxy URL.
The URL of the Redocly CORS proxy server is https://cors.redoc.ly
.
Customers who host Redocly products on-premises can use their own CORS proxy server, by setting the corsProxyUrl
value to their own CORS proxy server URL in the redocly.yaml
configuration file.
In Redocly Workflows, the CORS Proxy feature is enabled by default in newly created projects, and disabled in existing projects.
You can configure CORS Proxy for the following products:
API reference docs
- on-premise: Modify the value of the
corsProxyUrl
option in the.redocly.yaml
configuration file. The value can be the Redocly CORS proxy URL (https://cors.redoc.ly) or the URL of a custom CORS proxy server. - in Redocly Workflows: Navigate to API reference settings > General and (de)select the Disable CORS Proxy checkbox.
Developer portal
- on-premise: Modify the value of the
settings: corsProxyUrl
option in the.page.yaml
configuration file. You can set the value to either the Redocly CORS proxy URL (https://cors.redoc.ly) or the URL of a custom CORS proxy server.
To maximize the security and privacy of our clients and their users, Redocly does not collect or store any logs of traffic routed through the CORS proxy server.
About Redocly's CORS Proxy The CORS proxy server is hosted on Heroku, and as a result, its IP addresses are highly dynamic. For more information, refer to the official AWS documentation for currently published IP ranges.
We do not recommend adding entire IP ranges to your allowlist.
Enable the Try it API console
To enable the Try it console, set the showConsole
value to true
in the .redocly.yaml
configuration file. It is disabled by default.
referenceDocs:
showConsole: true # Enable the API Console (the Try it functionality).
Disable the Try it API console
To disable the Try it console, set the showConsole
to false.
referenceDocs:
showConsole: false # Disable the API Console (the Try it functionality).
You can also use the .redocly.yaml
configuration file to set other feature options. Learn more about reference doc-related configuration options.
Keep the configuration file in the root of your repository with your OpenAPI definitions, or upload the .redocly.yaml
file with your OpenAPI definitions.
Try it authentication
The Try it authentication only works for your active browser session. When users enter their credentials, these are saved in the session storage and removed after the session ends. If you open a new session, users will need to provide their authentication details to access the Try it feature.
Depending on the authentication scheme, Redocly can display the following:
http basic
- Username and password inputshttp bearer
- Input for the auth tokenapiKey
- Input for the API Key-
oauth2
implicit
- Inputs forclient_id
andscopes
and Authorize button which redirects user to an IdP:clientCredentials
- Inputs forclient_id
,client_secret
and Request Token button:authorizationCode
andpassword
- Input for the access token directly.
openIdConnect
- OAuth2 implicit flow UI (it works only for OpenID servers that supporttoken
response_type
right now, but Redocly will supportcode
once we add support forauthorizationCode
oauth2 flow)
How is the console implemented?
The Try it console is implemented as a lazy-loadable standalone plugin, so it does not increase the initial loading time.
The console plugin is loaded on demand when a user clicks the Try it button.