Skip to content

API Explorer

Oftentimes, we'd like to learn an API by trying it out (as opposed to just reading about it). Familiarizing yourself with an API typically involves interacting with its endpoints by giving various inputs and seeing how they respond to changing parameter values. In TORO Integrate, we fill this gap in learning via the API Explorer (a tool based on Swagger UI) which generates visual and interactive documentation for all of your Gloop RESTful APIs.

As with the basic Swagger UI, API Explorer also presents the Swagger definitions of all currently available RESTful APIs in TORO Integrate. It uses the information it gets from the specification to generate the necessary UI components that allow for the interaction between the user and the REST endpoints. No further configuration is needed because TORO Integrate automatically creates the Swagger specs on the your behalf.

Accessing API Explorer

You can access the API Explorer page in two ways:

  • Open your browser and directly visit /api-explorer or;
  • Via Coder

To open API Explorer via Coder, simply right click on your TORO Integrate instance in the Coder Navigator > Open API Explorer and then select which type of user you want to run API Explorer as. The table below describes the selectable types of users:

User Type Description
Active User Access API Explorer as the currently logged-in Marketplace User.
Integrate User Access API Explorer as a specific Integrate User. Secured REST APIs will not appear in API Explorer unless the Integrate User has sufficient privileges to access them.
Anonymous User Access API Explorer anonymously. This means secured REST APIs will not appear in API Explorer.

Accessing API Explorer via Coder Studio

Accessing API Explorer via Coder Cloud

User Interface

If you're already familiar with the Swagger UI, then using API Explorer will be a breeze. Even for new users, the experience will be smooth because of the fairly intuitive user interface. Below is a screenshot of the API Explorer page:

The *API Explorer* page

Read on below to learn more about API Explorer's components.

List of REST Endpoints

On the left side of the API Explorer page is a panel that lists all available REST endpoints, each described in the supplied Swagger specification. These REST endpoints are further grouped together by tags.

API Explorer's list of REST operations

The Swagger specification selected by default exclusively catalogs the REST endpoints intended for managing the TORO Integrate instance itself1 (as well as any Gloop services exposed using Ad-hoc, and Groovy services that have been annotated to do so). If there are other existing user-defined APIs in TORO Integrate, it is possible to select which Swagger specification gets fed to API Explorer via the select box located at the top of the page, like so:

Selecting which Swagger specification gets fed to API Explorer

Clicking on a group label allows you to see all REST endpoints belonging to the same tag.

REST Endpoint Details

Clicking on a particular REST endpoint's label on the left panel will prompt API Explorer to display the endpoint's information in the main panel, as shown below:

REST endpoint details, as shown in API Explorer

This panel can be further split into three sections:

  • The top-most section provides a description of the REST endpoint.
  • The following section, Parameters, describes the request parameters supported by the endpoint. It also features a Try it out! button which you can click in order to set the parameters' values and send the request yourself.
  • The bottom-most section, Response, describes the endpoint's possible HTTP responses coupled with some samples. If you've tried to send a request to the endpoint via the Try it out! > Execute buttons of the Parameters section, this part will be prepended with the details of the endpoint's actual response to your request.

Here's a GIF showing you how to send requests to a particular REST endpoint via API Explorer:

Sending an HTTP request via API Explorer

Authentication

Not all REST APIs are for public use. There will be REST APIs in TORO Integrate requiring certain access privileges2. To be able to interact with secured REST endpoints in API Explorer, one must be logged in as a Marketplace user or an Integrate User with granted access to the endpoints; else, non-accessible endpoints will not show up in API Explorer.

As stated earlier in the section above, the only time you will be able to select which user to log in as is before launching API Explorer.

Selecting which user to log in as in API Explorer

As stated earlier in the section above, the only time you will be able to select which user to log in as is before launching API Explorer.

Selecting which user to log in as in API Explorer

To log in as an Integrate User, click on the Authorize button at the top bar, fill out one of the forms in the dialog, and submit (by clicking the Authorize button).

API Explorer's *Authorization* modal

You can authenticate by providing an access token or a username and password. The GIF below demonstrates how to authenticate by submitting a username and password.

Authenticating as an Integrate User in API Explorer

To log in as a Marketplace user, you must be logged in to the Server Admin interface with Marketplace credentials.


  1. This particular Swagger specification is provided by the /api-docs/json/swagger endpoint. 

  2. See also: Securing Gloop Services, Securing Gloop APIs, Securing Groovy APIs, Securing Flux Services