API Docs Dashboard Tool

Overview

The API Docs Dashboard tool shows a dashboard view of the modules connected to every API (application programming interface) and remote execute. The tool builds documentation for the module when you select one from the dashboard. This documentation includes API call descriptions as well as their request and response parameters. The data type and description of each field also displays when you select one of the modules.

Remote executes interface with a module via an API call instead of loading the module in the browser. You build an API endpoint that other modules in your application can use when you build a remote execute module. So, the term API module can refer to a remote execute module or a module with a basic API call.

Follow three best practices to make sure this tool works:

  • Add the api Tag to your module. This makes your module easier to find in the API Docs Dashboard.

  • Follow the API Specification snippet to help you build API modules. APIs work as intended when you use these guidelines, and their documentation displays in the dashboard. Plus, The use of this template makes your Unqork configuration more consistent.

  • Set the Server Side Execution Only toggle to ON.

For more information on the API Specification Snippet, search API Specification Snippet in our In-Product Help.

Because the dashboard shows all API modules in your environment, it offers a variety of filters to help you find a specific API module. Available filters include:

  • Namespace

  • Title

  • ID

  • Path

Once you’ve found an API module, you can view its details. Along with basic title and module ID information, you can also view the API call’s:

  • Function description.

  • Method (GET/PUT/POST/DELETE).

  • Request and response parameters.

  • Request and response data types.

API Docs Dashboard Tool Access

This tool requires Creators Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform. to have specific role access in Environment Role RBAC (Role-Based Access Control) or WSRBAC (Workspaces Role-Based Access Control.

If using Environment Roles (not using WSRBAC):

  • Creator roles can view all data in this tool.

If using WSRBAC:

  • Creators can view data related to modules and workflows  inside Workspaces they have access to.

  • If a user cannot access specific records, it likely means they do not have access to the Workspace containing the module.

What You'll Learn

In this article, you'll learn how to:

Navigating the API Docs Dashboard

To view the details of an API module, you'll use the API Docs Dashboard table. By default, the table shows 10 entries. You can click the numbered buttons below the table to show more entries.

If you configure your modules correctly, you can view all their details in the dashboard. To the right of each table entry, you’ll see a View button. Click this button and you'll find the API call’s request and response parameters, data types, and notes.

You can see what the dashboard looks like below:

Filtering the API Docs Dashboard

All API modules created in the environment will appear in the API Docs Dashboard. The dashboard has 4 filters to help you find a module in your current environment. You can use any or all these filters, depending on how specific you want to be. As you enter text into the fields, the results will appear automatically. To clear all fields, just click the funnel icon to the far right. Let’s take a look at the filters:

Filter Description

Namespace

The Namespace is how the API Docs Dashboard identifies API modules. You'll enter a Namespace in the Module Tags when you create your module.

For the dashboard to find your module, you must enter api into the Module Tags. If you want to further organize your API modules, you can be more descriptive by entering api-namespace: someNamespace.

For example, if you had a couple of modules specific to dogs, you can enter the following Namespaces: api,api-namespace:dogs. After you add this Namespace, dogs will appear in the Namespace column of the API Docs Dashboard.

The Namespace field uses autocomplete to suggest Namespaces used elsewhere in the environment.

Title

This is the title of your module.

This is not your module ID.

ID

This is the module ID of your module.

Path

This is the module path of your module. You can find this path right below the module's title.

Navigating Your API Documentation

Once you’ve found your API module, click on the View button to the far right. After clicking the button, you’re directed to a new page with all your API module details. On this page, you'll find:

  • The API module’s title.

  • A brief description of the API module.

  • The API call’s method.

  • A link that directs you to Server-Side Module Execution.

  • The API request table.

  • The API response table.

Here's an example of what you might see when you view your API details:

Viewing the Request and Response of Your API Module

You’ll find most of your API module’s information in the Request and Response tables. Let’s look at the information you’ll get from each table.

In the Request table, you’ll see:

Filter Description

Parameter

This is the Property ID from your API module.

Type

This lets anyone know the data type of your API's request. When creating an API module, you add data types into the Module Tags. The correct way to enter them is type:YourDataType. The API Specification snippet gives you several types to choose from, depending on your API:

  • type:string: If the data is alphanumeric.

  • type:number: If the data is an integer or a float point number.

  • type:boolean: If the data is boolean (true or false).

  • type:array: If the data type is an array.

  • type:object: If the data type is an object.

  • type:objectId: If the data type is a MongoDB unique identifier.

The table only shows the defined data type. For instance, if you entered type:dogs in the Module Tags, dogs will appear in the Request table.

Required

This lets you know that the module's API parameters are required or not. If a checkmark exists, this means the parameter is required. If blank, the parameter isn’t required.

Comments

This is typically a description of the API request. For example, the description could be: “The API call gets the name of a dog.”

Here's an example of a Request table you might see for your API module:

In the Response table, you’ll see:

Filter Description

Parameter

This is the Property ID from your API module.

Type

This lets anyone know the data type of your API's response. When creating an API module, you add data types into the Module Tags. The correct way to enter them is type:YourDataType. The API Specification snippet gives you several types to choose from:

  • type:string: If the data is alphanumeric.

  • type:number: If the data is an integer or a float point number.

  • type:boolean: If the data is Boolean (true or false).

  • type:array: If the data structure is an array.

  • type:object: If the data structure is an object.

  • type:objectId: If the data is a MongoDB unique identifier.

The table only shows the defined data type. For instance, if you entered type:dogs in the Module Tags, dogs will appear in the Response table.

Comments

This is typically a description of the API response. For example, a description could be: “Ralph is the name of the dog.”

Here's an example of a Response table you might see for your API module: