API

Description

THe API module allows you to document APIs by using OpenAPI Specification and provides a visual overview of the APIs documented and for users to try out the APIs.

Currently the API module only supports editing OpenAPI Specification 3.0 in JSON format (import/export supports both YAML and JSON formats).

For more information on OpenAPI Specification 3.0, visit https://spec.openapis.org/oas/v3.0.3.

Module Interface

Interface	Description	Required Privilege
API	Allows access to API management page.	mod-api
API Editor	Allows access to API Editor.	mod-api-editor

Add API

This function allows you to add a new API.

To add a new API, click on the “Add” button at the upper right corner of the page.

The “Add API” dialog box will appear.

Field	Description	Mandatory	Input Type	Constraints	Default Value
Name	Unique name assigned ti the API that would be used as its identifier.	Y	Text Field	Any text. The value must not exist in the current list of names, regardless of status (published or unpublished) and ownership. The value is case-sensitive.	Empty String
Copy From	Indicates what template the API would be based on. Selecting “Blank API” results in using a blank canvass as a starting point while selecting an existng API would result in having the selected API as the starting template.	Y	Drop-down list	One value can be selected. Options are: - Blank API - Names of all enabled API the user currently has read access to	“Blank API”

Key in a unique name for the new API in the “Name” field and select either to copy from an existing API or a blank API from the drop-down list in the “Copt From” field. Click on the “OK” button to create a new API.

If the name already exist or no name is entered, the relevant error message will appear.

Upon creating the API, the main page of the API Editor will appear.

Refer to API Editor for more details on how to setup the API. Do note that all new APIs are not published.

Edit API

This function allows you to edit the name and roles allowed to access the API.

To edit the API, click on the “Edit” icon under the “Actions” column corresponding the desired API.

The “Edit” dialog box will appear.

Edit as desired and click on the “Save” button to save the changes. Click on the “Cancel” to abort the action.

Open API

This function allows you to launch the API Editor for editing.

To access the API Editor, click on the name of the API under the “Name” column. The main page of the API Editor will appear.

Refer to API Editor for more details.

Export API

This function allows you to export the API either in JSON or YAML format.

To export an API, click on the “Export” icon under the “Actions” column corresponding the desired API.

A “Download” dialog box will appear.

Select the desired format (JSON or YAML) from the drop-down list and click on the “OK” button to download the API. To abort the action, click on the “Cancel” button.

The downloaded API will have the following filename: <api name>.api.<JSON or YAML>.

Upload API

This function allows you to upload the API either in JSON or YAML format.

To download an API, click on the “Upload” button at the upper right corner of the page.

A “Upload” dialog box will appear.

Single File

Click on the “Choose File” and browse to the location of the desired file. The “Name” field will be automatically filled with the filename of the selected file.

If no file is selected, an error message will appear.

The name must be unique. If the name already exist, an error message will appear when you attempt to upload the file.

To overwrite an existing API, select the “Overwrite” checkbox.

Click on the “OK” button to upload the file or click on the “Cancel” button to abort the action. Upon successful upload, a message will appear.

Zip Files

Browse to the location of the zip file to be uploaded. The name of the APIs will be extracted from the zip file. Click on the “OK” button to upload the report. The “Upload Results” dialog box will display the results of the uploading.

Those results in black are uploaded successfully while those in red indicates upload failures with their relevant messages. Click on the “Close” button to close the dialog box.

Publish/Unpublished

Owners of each API can publish the API spec for everyone with access to the API module to view the API spec.

Published APIs are indicated with a green tick under the “Published” column in the management page while unpublished APIs are indicated with a red cross. All newly added APIs are unpublished by default.

To publish an API, click on the “Publish” icon under the “Actions” column corresponding the desired API.

A message will appear after the API is published successfully.

The API is now indicated with a green tick under the “Published” column in the management page. The icon is now replaced with the icon, and the and icons are not available as well. To edit this API, you will need to unpublish the API.

To unpublish an API, click in the “Unpublish” icon under the “Actions” column corresponding the desired API. A message will appear after the API is unpublished.

The unpublished API is now editable and deletable as the and icons are now available.

Delete

To delete an API, click on the “Delete” icon under the “Actions” column corresponding to the desired API.

There is an option to undo the deletion. A notification with an “Undo” button appears right after clicking on the “Delete” icon.

Upon clicking on the “Undo” button, the deleted API is restored and is added back to the list of APIs.

More Actions

This function allows you to perform an action on several APIs at the same time.

When the “More Actions” button located at the upper right corner of the page is clicked, a list of available actions are displayed. If no API is selected prior clicking the button, there will be fewer actions available. To select an API, select the checkbox next to the name of the API.

Option	Description
Select All	Selects all APIs in the list.
Select None	Unselects all APIs.
Invert Selection	Inverts the current selection. That is, any APIs selected will be unselected and vice versa.
Set Roles	Selects the roles to be assigned to the APIs.
Download	Downloads multiple APIs as a zip file. If only one API is selected, the selected API will be downloaded as a JSON file.

To set the roles, select the desired APIs. Click on the “More Actions” button and select the “Set Roles” option. The “Set Roles” dialog box will appear.

Select the desired roles and click on the “OK” button to save the change. There is a search function, as well as Select All, Select None and Invert Selection buttons above the role options that may assist you in the role selection.

To download multiple APIs, select the desired APIs. Click on the “More Actions” button and select the “Download” option. The “Download” dialog box will appear.

Key in a name for the zip file and click on the “OK” button. The APIs will be downloaded as a zip file with the filename provided. The individual downloaded API files in following format: <filename>.api.json.

If only one API is selected, the API will be downloaded in JSON format.

Refresh

After performing actions on the browser/tab, the list is reloaded to display the list of APIs in the page. The manual “Refresh” button is available and is particularly useful if you or others have opened multiple pages and making changes.

The “Refresh” button is found at the upper right corner of the page. Clicking on it reloads the list.

Search

There is a cross-field search function for the list of APIs. It is located at the upper left corner of the page.

This provides an easy way to search through the list of APIs. It is case-insensitive and displays the APIs that have the entered search value in any of the values of the fields below:

• Name
• Owner
• Roles
• Last Modified

Alternatively, you can click on the any role or owner under the “Roles” or “Owner” columns respectively to aid the search for the records in the page.

In the example above, records that are assigned the role “tester” are shown.

These two search methods can be combined together, with each criteria separated by a comma.