Configuring Scripted REST API

Scripted REST API functionality allows application developers to implement custom web APIs.

Define API actions and request parameters that utilize the customized API logic (including but not limited to: the script implementing method; request path; authentication require; parameter obligate for related modules and actions).

Role required: admin.

Scripted REST API URIs

Scripted REST API URIs have the following format:

{your_instance_url}/api/{application}/{module}/{version}

URI analisys

URI part	Description
{your_instance_url}	Path to the instance where the scripted REST API can be accessed.
{application}	The application within of which the implementing is being conducted.
{module}	API module containing references to essences implementing the customized REST API logic (actions, request parameters, and so on). API modules are described below.
{version}	(optional) Version of the API endpoint if versioning is used, for example, v1.

How to implement your custom API

Create an API module.
Create an API version.
Configure API actions.
Configure API request parameters.
Bind API request parameters with appropriate API modules and actions.

Creating an API Module

API module is a connecting element for API versions and API actions.

To create an API Module, please complete the steps below:

Navigate to Scripted REST API → API Module.
Click New and fill in the form.
Click Save or Save and Exit to apply changes.

API Module form fields

Field	Description
Name	Specify the API module name.
Path	Relative path to the API module, for example, '/api/cmdb.'
Active	Select this checkbox to make the module active or inactive. When set to FALSE, you'll be unable to choose this module in referencing tables (API Version, API Action, API Module Request Parameters).

Creating an API Version

Scripted REST API enables versioning, allowing developers to deploy changes without affecting existing integrations.

To configure an API version, please complete the steps below:

Navigate to Scripted REST API → API Version.
Click New and fill in the fields.
Click Save or Save and Exit to apply changes.

API version form fields

Field	Description
Module	Specify the API module created earlier for this version.
Active	Select this checkbox to make the version active or inactive. When set to FALSE, you'll be unable to choose this version in referencing tables (API Action).
Path	Path to the API version, for example, 'v1'.

The first version, that is v1, ready for deployment, is created automatically when the API module is created.

API requests without a version specified automatically use the last version having Active state.

Configuring an API Action

In there, you can configure an action implementing the logic and behavior of your customized API method.

Your actions created earlier can be reached by URI like:

{your_instance_url}/api/{application}/{module}/{action}

or

{your_instance_url}/api/{application}/{module}/{version}/{action}

The second URI sample is used in case of the versioning enabled.

To configure an API action, please complete the steps below:

Navigate to Scripted REST API → API action.
Click New and fill in the fields.
Click Save or Save and Exit to apply changes.

API action form fields

Field	Description
Name	The action name.
Path	A path for API action.
Active	Select this action to make the version active or inactive. When set to FALSE, you'll be unable to choose this version in referencing tables (API Action Request Parameter).
Is Authentication Required	Select this checkbox if the request requires authentication before execution. The token is transmitted in the request header. By default, this statement is equal to TRUE.
Module	Choose the API Module created earlier (module must be activated before choosing). This field references the API Module (sys_api_module) table.
Version	Choose the API version created earlier (version must be activated before choosing). This field references the API Version (sys_api_version) table.
HTTP Method	Select the method this action implements (GET, or POST, for example).
Script	Specify a script implementing your action. You can use SimpleRequest and SimpleResponse server-side API classes there.

Configuring API request parameters

In there, you can specify the request parameters, for example, you can make the parameter mandatory for all referenced API essences.

To configure this, please complete the steps below:

Navigate to Scripted REST API → API Request Parameter.
Click New and fill in the fields.
Click Save or Save and Exit to apply changes.

API Request parameter form fields

Field	Description
Name	The request parameter name.
Is required	Select this checkbox to make this parameter mandatory for all referenced API essences.

Configuring API action request parameters

In this section, you can bind specified API module with relevant request parameters.

To configure them, please complete the steps below:

Navigate to Scripted REST API → API Action Request Param.
Click New and fill in the fields.
Click Save or Save and Exit to apply changes.

API action request parameters form fields

Field	Description
Action	Specify the API action created earlier for which you need to define a related API request parameter. This field referenced the API action (sys_api_action) table.
Request parameter	Specify a request parameter related to this action. When specified, an action referenced to this request parameter can use its options predefined in the API request parameters dictionary. This field references the Request Parameter (sys_api_request_param) table.

Configuring API module request parameters