release notes

OpenAPI support for Indicium

Related products: Indicium Service Tier
OpenAPI support for Indicium
The 2019.1.7 release of Indicium has added support for an OpenAPI endpoint.



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.

After following the steps to make the API endpoints available through Swagger UI, I do not get further at the step for retrieving the /openapi JSON. When executing a GET request I get a 500 error message. 

In the example you describe using https://localhost/iam/myapp/openapi. I assume localhost can also just be replaced with our DNS name https://dnsname/iam/test/openapi? 

 

[inf] Request finished HTTP/1.1 GET - 0 - 500 - - 30403.4826ms (791a596a)

 


Additional information: 

✔️ Our Indicium appsettings.json file does not contain the property "HideMetaDataDocument"

✔️ Executing a GET request to the /$metadata or another endpoint of our application does work.  

 


Hello Dennis,

Could you check Indicium’s error log? It will probably contain more information regarding this error.


The starting point from the indicium log error was:

System.ArgumentException: An item with the same key has already been added. Key: transl_created_by_administration_id   
at System.Collections.Generic.Dictionary`2.TryInsert(TKey key, TValue value, InsertionBehavior behavior)  

GET $metadata​​​​

by consulting $metadata we found out that for columns with a look-up reference a <NavigationProperty> is generated using the prefix transl_ this got in conflict with the fact that we also have column names built with transl_. 
 

NavigationProperty transl_

Because these fields are only in views that are used for reporting purposes the lookups are redundant. Removing the lookup resulted in the fact that we could retrieve the openapi JSON.
 

For the long term, Thinkwise (@Vincent Doppenberg) has agreed to replace the prefix transl_ with transl- or any other prefix that does not pass SF column validation.