API Explorer

API Explorer UI tutorials

These tutorials describe how to use the API Explorer web utility, which makes it easy to create and run FairCom’s jsonActions.

All FairCom JSON APIs can be tested using API Explorer. The JSON APIs include JSON Admin API, JSON Hub API, and JSON MQ API

Access API Explorer

  1. With the FairCom server running, open the browser-based menu (https://localhost:8443/) to access the FairCom graphical user interfaces.

    Note

    See Manage certificate warnings for issues accessing the tools.

     
  2. Access the API Explorer with either Data Explorer or MQ Explorer:
    • In the Data Explorer, through the API Explorer tab.
    • In the MQ Explorer, through the Control menu ().
 
 

Connect to a database

There are three ways you can connect to a database with a new session.

Figure 1. Connect to Server and Database window

Connect to a database with no prior connection

  1. Select the database you wish to connect to in the Server navigation window.
  2. Click Yes in the New Session pop-up window.
  3. Click Connect to Server in the Connect to Server and Database window (see Figure 1, “Connect to Server and Database window”).
  4. Observe your database in the new session.

Right-click on a database you have a current connection to

  1. Right-click the database you wish to connect to in the Server navigation window and click Connect ().
  2. Click Connect to Server in the Connect to Server and Database window (see Figure 1, “Connect to Server and Database window”).
  3. Observe the connection to the database you selected in a new session (a new browser tab).

Select a database that you have a current connection to

  1. Select the database you wish to connect to in the Server navigation window.
  2. Select Connect () from the Menu dropdown menu.
  3. Click Connect to Server in the Connect to Server and Database window (see Figure 1, “Connect to Server and Database window”).
  4. Observe the connection to the database you selected in a new session (a new browser tab).
 
 

Select an API

  1. Click Select API to open the API dropdown menu.
  2. Select from the list of available APIs:
    • JSON Admin API
    • JSON DB API
    • JSON MQ API
    • JSON Hub API
  3. Observe the selected API's actions, templates, and properties.
 
 

Load an action

There are four separate ways you can load a JSON action into the request window:

  • You can select an action from the drop-down menu. This auto-populates the request window.
  • You can paste an action from the clipboard into the request window.
  • You can load an action into the request window from text that is stored in a file.
  • You can manually type or modify an action in the request window.

Here we show how to load the request using the drop-down menu.

Once an API is selected, the JSON Actions drop-down menu contains a list of the actions available.

  1. Click the JSON Actions dropdown menu.
  2. Select an action — for example, createTable.

    Note

    Some actions require preliminary actions to be run first — for example, before selecting and running deleteTable you must first have selected and run createTable.

     
  3. Observe the JSON request example in the API Request editor.
 
 

Update authToken

All API actions (except createSession and pingSession) require a valid authToken property value.

  1. Click the Apply defaults to JSON request icon ().
  2. Observe your supplied, valid authToken property value.

    Note

    When API Explorer first runs, it automatically runs the createSession action, creating a server session and returning a valid authToken value. API Explorer uses this value when you click the Apply defaults to JSON request icon after you load examples from action templates.

     
  3. If you wish to use a different authToken than the one supplied at createSession, use the Property Defaults feature to set the authToken to a different authorization code.
When an authToken is invalid the server returns one of the following errors:
  • Error 60025
    "errorCode": 60025,
"errorMessage": "Invalid parameter - Missing authToken parameter in the request. The only actions that do not require authToken are createSession and pingSession in the admin API."
  • Error 60031
    "errorCode": 60031,
"errorMessage": "Not possible to find valid session for the provided token."
 
 

Run an action

Figure 2. Run an action
  1. Click the Send Request icon () to run the current action with the properties in the API Request editor (see Figure 2, “Run an action”.

    Tip

    Keyboard shortcuts:

       For Windows use CTRL+ENTER.

       For Linux use COMMAND+ENTER.

     
  2. Observe the response and ensure the action completed successfully.

    Note

    "errorCode" with a value of 0 indicates success. "errorCode" with a non-zero value indicates a failure. See Errors and contact FairCom for more information about an error.

     
  3. Check the Accumulate Results? checkbox in the API Response header to accumulate the results each time the API Request editor example is run.

    Note

    When the Accumulate Results? checkbox is left unchecked the API Explorer clears the results from the API Response viewer each time the request example is run.

     
  4. Click the Download results icon () to download the results to a disk.
  5. Click the Clear results icon () to clear the API Response viewer.
 
 

Get help for an action

FairCom provides online documentation for each action.

  1. Click the action's Show help for selected action icon () for available online documentation.
  2. Observe the documentation in a new tab.
 
 

Change the JSON example

When you select an action from the JSON Actions dropdown menu, API Explorer loads an example JSON request into the API Request editor.

  1. If preferred, select from pre-formatted templates in the Templates dropdown menu.
  2. In the API Request editor, edit the existing example JSON.
  3. Alternatively, paste or type in your own examples.
 
 

Load an example from a disk

Figure 3. Upload JSON example from a disk
  1. Click the Upload set of JSON files icon ().
  2. Select the JSON example file.
  3. Click Open.
 
 

Save an example to a disk

Figure 4. Save a JSON example to a disk

  1. Click the Export JSON icon ().
  2. Observe the download in the download bar.
 
 

Display or hide the default property list

  1. To view the Property defaults panel, click the Show property defaults icon (ShowPropertyDefaultsIcon.png).
  2. Observe the Property Defaults panel.
PropertyDefaultsPanel.png
  1. To hide the Property Defaults panel, click the Show property defaults icon () or the Close Panel icon ().
  2. Observe the API Explorer without the Property Defaults panel.
 
 

Change the default values of properties

The Property Defaults panel allows you to create a list of default values that apply to the JSON example displayed in the API Request editor.

Figure 5. Property Defaults panel with an added default
  1. Click the Show property defaults icon () to view the Property Defaults panel.
  2. Click the Add Default button () to add a property to the list.
  3. Edit the Property Path to match the path that identifies the property in the JSON — for example, params.databaseName (see Figure 5, “Property Defaults panel with an added default”).
  4. Edit the Default Value to your desired default value — for example, edit the params.databaseName default value to test_db.
  5. Click Update to save your changes.
  6. Click the Apply defaults to JSON request defaults to JSON request icon () to apply the new default values.
  7. Alternatively, click the Remove icon () next to the default property to remove it.
  8. To hide the Property Defaults panel, click the Show property defaults icon () or the Close Panel icon ().
 
 

Display or hide the property list

  1. To view the Action Properties panel, click the property Show all action properties icon ().
  2. Observe the Action Properties panel.
  3. To hide the Action Properties panel, click the property Show all action properties icon () or the Close Panel icon (ClosePanelIcon.png).
  4. Observe the API Explorer without the Action Properties panel.
 
 

Use the property list

The Action Properties panel is a list of available properties for the selected action.

Figure 6. Action Properties panel

 
 

 

api viewer api browser

Was this article helpful?

Give feedback about this article

Related Articles