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, an 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” panel 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 
“Open API” icon under the “Actions” column corresponding the desired API.
The main page of the API Editor will appear.
Refer to API Editor for more details.
Download API
This function allows you to download the API either in JSON or YAML format.
To download an API, click on the 
“Download” 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.
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 the selected file is a YAML file, a message will appear in the dialog box.
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.
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.
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
