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 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 your behalf.
Accessing API Explorer
You can access the API Explorer page in two ways:
- Open your browser and directly visit
- Via Coder
To open API Explorer via Coder, simply right click on your TORO Integrate instance in the Coder Navigator view > 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:
|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.|
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:
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 defined in the supplied Swagger specification. These REST endpoints are further grouped together by tags.
The Swagger specification selected by default exclusively catalogs the REST endpoints intended for managing the TORO Integrate instance itself1, ad-hoc Gloop services, and Groovy services that have been annotated with Swagger annotations. 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:
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:
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, Responses, 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:
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.
If you're using Coder, you will be able to immediately select which user to log in before launching API Explorer. If you need to change the current user, just click on the Change Credentials (or Login, if not logged in yet) button at the top of the page, and supply the required credentials. The GIF below shows a quick demonstration of this process:
If you're on the Server Admin UI, opening
/api-explorer on your browser should automatically log you in as the
logged in Marketplace user.