Familiarizing yourself with an API typically involves interacting with endpoints by giving various inputs and seeing how they respond to changing parameter values, aside from reading documentation. In Martini, 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 vanilla Swagger UI, API Explorer also presents the Swagger definitions of all currently available RESTful APIs in Martini. 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 Martini automatically creates the Swagger specs on your behalf.
Accessing API Explorer
You can access the API Explorer page in two ways: (1) open your browser and directly visit
(2) via the IDE.
To open API Explorer via the IDE, right click your Martini instance in the Navigator view > Open API Explorer. 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.|
|Martini User||Access API Explorer as a specific Martini user. Secured REST APIs will not appear in API Explorer unless the Martini user has sufficient privileges to access them.|
|Anonymous User||Access API Explorer anonymously. This means secured REST APIs will not appear in API Explorer.|
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 only defines REST endpoints intended for managing the Martini instance1, as well as Groovy services that have been annotated with Swagger annotations. If there are other existing user-defined APIs in Martini, 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 Martini 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 a Martini user with granted access to the endpoints; else, non-accessible endpoints will not show up in API Explorer.
In Martini, 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 Martini Runtime Admin UI, opening
/api-explorer on your browser should automatically log you in as the
logged in Marketplace user.