Explore a Smart API - Intergraph Smart API Manager - 5.0 - Help

Intergraph Smart API Explorer

Smart API Explorer is a web client that lets you explore the available resources for a Smart API. Smart API Explorer reads an Open API (formerly known as swagger) resource from the current Smart API. This resource is located at: <service root>/doc.

The concept is simple: read the Open API resource and display information about the API inside a web client that is easy-to-read, informative, and discoverable. The intuitive interface makes it easy for a programmer to browse the API. You can discover resource names, data structures, hierarchy, and other information relevant to developing software with a Smart API.

1. On the left panel, click Smart APIs .

2. Click the Smart API in the grid to see its details.

3. On the top section of the details page, click to explore the Smart API.

   If the icon is disabled and its tooltip reads Documentation Unavailable, the Smart API does not support the <service root>/doc resource required by Smart API Explorer.

   If <service root>/doc is a secured resource, click AUTHORIZE to explore the Smart API.

   The credentials you use to log into Smart API Manager must belong to a group authorized to access the current Smart API. If not, the Smart API Explorer page displays an Auth Error: "User is not authorized to call the requested resource." Log out of Smart API Manager and log in with credentials authorized to access the Smart API you want to explore.

User Interface

Smart API Explorer displays resources in sections. Each section contains rows representing the HTTP verbs you can call. You should start exploring with the GET rows.

Each row displays a icon. The lock must be in the position in order to call secured API resources. Click any one of the icons on the page, click the (Required) scope and then AUTHORIZE to gain access to secured resources. If you have already clicked AUTHORIZE to access Smart API Explorer, the icons should already be displayed in the position.

Click a row to expand its content and explore. The expanded row contains two main sections: Parameters and Responses. By default, the application is in review mode, meaning you can explore information but cannot execute a call to the API.

• Parameters - This section lists the standard parameters (OData query options) available for the selected resource and verb.

  • TRY IT OUT - Click this button when you are ready to execute a call to the API. It enables the EXECUTE button and lets you set values for any required parameters.

    The EXECUTE button changes to a CANCEL button, which you can click to revert back to review mode.

  • EXECUTE - Click this button to execute the call against the Smart API. A Curl command-line displays the syntax used to call the Smart API resource, including all parameters, request headers, etc.

• Responses - This section lists the expected HTTP status codes, response body and headers for a request.

  • Example Value/Model - Click Model to explore the data format for a response. You can view all properties along with a logical description and their data types, drill down through contained navigation properties, and so on.

Smart API Embedded Explorer

A Smart API may also support an embedded version of Smart API Explorer, accessible directly from a browser.

Browse to: <service root>/doc/explorer to verify direct access.

To take full advantage of the embedded Smart API Explorer requires authorization. You must ensure the following requirements are met in order to AUTHORIZE:

1. Register a Smart Client (Implicit flow), with the same instance of Smart API Manager where the Smart API is registered (its trusted OAuth issuer).

2. Add the following Post-Login Redirect URI for the Smart Client: <service root>/doc/explorer/oauth2-redirect.html

3. Add the Smart Client ID to the configuration file for the Smart API:

   • For a web.config (XML) file:

     <!-- Enable Open API specification endpoint with Swagger UI -->

     <documentation enableSwaggerUi="true" clientId="<Smart Client ID>" clientSecret="" />

     </intergraph.webApi>

   • For an appsettings.json file:

     {"Hexagon.SmartApi":

     {"documentation":

     {

     "EnableOpenApiUi": "true",

     "ClientId": "YourSmartClientID"

     }

     }

     }