This endpoint can be used in collaboration with tools like Postman or Swagger UI to explore what kinds of endpoints/requests an application exposes through Indicium.
By exploring the application's endpoint/request definitions through these tools, a developer can more easily prototype and test their own requests when, for example, building an external service that consumes data from the application.
Accessing the endpoint
To access the OpenAPI endpoint of an application, send a GET request to the openapi path on the regular application root endpoint.Given an Indicium that is running on localhost and an application with the alias myapp that has been synced to IAM, the OpenAPI URL would be:
- https://localhost/iam/myapp/openapi
Do note that, like all application endpoints, the OpenAPI endpoint requires a client to login before it can be used.
On success the response will contain a JSON object describing the available requests for the application in OpenAPI specification version 3 format.
Postman
To import the OpenAPI definition into Postman first navigate to the application's openapi endpoint using a browser.Save the entire JSON document to a file or copy it from within your browser window.
In Postman, open the workspace where the collection must be imported to and click the Import button.
The window that pops up offers several ways to import an OpenAPI JSON document.
For instance by selecting a saved OpenAPI document:
Or pasting the document's content directly:
Do note however, that because the openapi endpoint requires authorization, the Import From Link option cannot be used.
The imported collection should now have been added to the Collections tab.
Next, select a request and add an authorization method that works with the Indicium in question.
For instance, Basic Auth with a username and password.
Please note:
Postman currently has an issue with importing OpenAPI requests for OData when the request contains a key parameter.
These parameters will show up in the Params tab as so called Path Variables which are formatted like :variable in the request itself.
While it may look like a value can be set for these variables using the Params tab, when sending the request, the variable name is not being replaced with the entered value.
This means that requests containing a key will not work directly after importing the OpenAPI document.
For now, to get around this, substitute the variable directly in the request url before sending it.
An issue has been filed on the postman repository to track this.
Swagger UI
To use Swagger UI to explore the available requests for an application it must first be deployed to the same server (and domain) Indicium is running on.The following example will be using the dist deployment variant.
This basically means that one must download the source code archive from the latest release and deploy the contents of the dist directory as a static website.
To do this using IIS, create a swagger directory under the same website root that Indicium was deployed to.
Then copy the contents of the dist package to it.
Navigate to the swagger path using a browser, in the case of the example that would be http://localhost/swagger, and the Swagger UI should show up.
Make sure your browser session has been logged into the target Indicium by opening a tab and navigating to any of the endpoints that are protected with authentication.
The openapi endpoint is one of them so that can be used if you do not know any others.
After logging in, enter the openapi endpoint url for the application whose endpoints you want to see in the Swagger UI search bar and click Explore.
The endpoints for the application should now be loaded and shown on screen.
Click on any of the endpoints to expand them and try them out.