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).

Scripted REST API URIs

The format of scripted REST API URIs is represented below:

{your_instance_url}/v1/api/{applicationSlug}/{module_path}/{version}/{action_path}?{params}

URI analysis

How to implement your custom API

1. Create an API module.
2. Create an API version.
3. Configure API actions.
4. Configure API request parameters.
5. 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:

1. Navigate to Scripted REST API → API Modules.
2. Click New and fill in the form.
3. Click Save or Save and Exit to apply changes.

API Module form fields

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:

1. Navigate to Scripted REST API → API Versions.
2. Click New and fill in the fields.
3. Click Save or Save and Exit to apply changes.

API version form fields

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}/v1/api/{application}/{module_path}/{action_path}

or

{your_instance_url}/v1/api/{application}/{module_path}/{version}/{action_path}

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

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

1. Navigate to Scripted REST API → API actions.
2. Click New and fill in the fields.
3. Click Save or Save and Exit to apply changes.

API action form fields

const simpleInstanceUri = ss.getProperty('simple.instance.uri');
const URL_BASE = (simpleInstanceUri.startsWith('https://')) ? simpleInstanceUri : `https://${simpleInstanceUri}`;
const authRequest = sws.restRequestV1();
authRequest.setRequestUrl(`${URL_BASE}/v1/auth/login`);
authRequest.setRequestMethod('POST');
authRequest.setRequestHeader('Content-type', 'application/json');
const payload = {
    "username": "admin",
    "password": "qwerty123456"
}
authRequest.setRequestBody(JSON.stringify(payload));
const authResponse = authRequest.execute();
if (JSON.parse(authResponse.getBody()).status === 'ERROR') {
  ss.error(JSON.parse(authResponse.getBody()).errors[0].message);
  ss.info('Check credentials at 10..11 lines of current script');
  return;
}
ss.info(JSON.parse(authResponse.getBody()).data.auth_key);
// Info: 5WvOT9Ejlxd6Gb8bkCWMtG3XXMYcoDDJ

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:

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

API Request parameter form fields

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:

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

API action request parameters form fields

Configuring API module request parameters

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

To configure this relationship, please complete the steps below:

1. Navigate to Scripted REST API → API Module Request Parameters.
2. Click New and fill in the fields.
3. Click Save or Save and Exit to apply changes.

API Module request parameters form fields

Example case

Consider a case of implementing Scripted REST API returning data in response to a POST request.

The request looks like: http://your-instance-url.example.com/v1/api/c_simple/api_module_path/api_action_path?param_1=value_1

Your actions should go as follows:

1. Create an API module. Fill in the fields as given below:
   1. Name – type a module name.   
   2. Path – type api_module_path there.
   3. Select the Active checkbox to activate the module.
2. Create an API version out of API module created earlier. Fill in the fields as given below:
   1. Name – type a version name.
   2. Module – this field populates automatically with reference to the API module
   3. Path – type v1 there,
   4. Select the Active checkbox to activate the version.
3. Create an API action out of API version created earlier. Fill in the fields as given below:
   1. Name – type an action name.
   2. Path – type api_action_path there.
   3. Module – this field populates automatically with reference to the API module.
   4. Version – this field populates automatically with reference to the API version.
   5. HTTP Method – select POST in this list.
   6. Select the Active checkbox to activate the version.
   7. Is Authentication Required – select this checkbox if you are sending authenticated requests.
   8. Script – put a script here given in a code example below .
4. Send a POST request to the URL given in the introductory. You can use any tool you are comfortable with (cURL, or Postman, or any other one).
   1. Substitute the example domain (your-instance-url.example.com) in the endpoint and in the script body with your real hostname.
5. Check logs (the sys_log table) to locate responses.

(function (request, response) {
    ss.info("getBody(): " + JSON.stringify(request.getBody()));
    ss.info("getHeader('accept-encoding'): " + JSON.stringify(request.getHeader('accept-encoding')));
    ss.info("getHeaders(): " + JSON.stringify(request.getHeaders())); // {"accept-encoding":["gzip, deflate, br"],"postman-token":["7803024c-7e21-4e0d-840b-392931597c2c"],"cache-control":["no-cache"],"accept":["*/*"],"user-agent":["PostmanRuntime/7.26.8"],"content-length":["0"],"connection":["close"],"x-nginx-proxy":["true"],"host":["your-instance-url"],"x-real-ip":["XX.XX.XX.XX"],"content-type":[""]}
    ss.info("getQueryParams(): " + JSON.stringify(request.getQueryParams())); // {"param_1":"value_1"}
    ss.info("getQueryString(): " + request.getQueryString()); // param_1=value_1
    ss.info("getUri(): " + request.getUri()); // /v1/api/c_simple/api_module_path/api_action_path?param_1=value_1
    ss.info("getUrl(): " + request.getUrl()); // https://your-instance-url.example.com/v1/api/c_simple/api_module_path/api_action_path?param_1=value_1
    response.setBody({
        "status": "ok",
        "support_phone": ss.getProperty('simple.auth_page.support_phone')
    });
})(SimpleApiRequest, SimpleApiResponse)