Scripted REST API

The Scripted REST API is used to create custom web APIs for instance integrations with external applications. You can define a server script called by a REST request from an external system.

A script can process request parameters, perform actions on the instance, and generate a response. The configured REST API creates an endpoint for the requests from external systems, including other SimpleOne instances.

tip

Role required: admin.

Endpoint setting

To set an endpoint, complete the steps below:

1. Create an API Module. Navigate to Scripted REST API → API Modules.

2. Click New and fill in the fields.

   Field	Description
   Name	Specify the API module name.
   Path	Specify a relative path to the API module, for example, support.
   Active	Select this checkbox to make the module active. This enables you to select this module in the referencing tables: API Version, API Action, and API Module Request Parameters.

3. Click Save or Save and exit to apply the changes. A related record API Version is created and located in the related list.

4. Click the API Version record in the Related list to open it. You can add another record of the API module version in the related rist if needed.

   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 select this version in referencing tables (API Action).
   Path	Specify a path to the API version, for example, v1.

5. In the Related List area, select the API Action tab and click New.

   Field	Description
   Name	Specify the action name.
   Path	Specify a path for API action.
   Active	Select this action to make the version active. When set to false, you cannot select this version in referencing tables (API Action Request Parameter).
   Is authentication required	Select this checkbox if the request requires authentication before the execution. The token passes in the request header. By default, this statement is equal to true.
   Module	Select the API Module created earlier (activate module before selecting). This field references the API Module (sys_api_module) table.
   Version	Select the API version created earlier (activate version before selecting). This field references the API Version (sys_api_version) table.
   HTTP Method	Select the method this action implements (for example, GET or POST).
   Script	Specify a script that implements your action using the Server-Side API, SimpleApiRequest and SimpleApiResponse side API classes there.

note

You can create an API action to run its script when a request for action is received.

You can state a version to the request for action:

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

Or you can omit it:

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

API requests without a version specified automatically use the last active version.

6. Fill in the Name and the Path fields. The example value of the Path field is tickets-count.
7. In the HTTP Method field, specify the method to call the action.
8. In the Script filed, add a script to call when a REST request for the action occurs. To work with the REST API requests in the SimpleOne platform, the SimpleRestRequest and SimpleRestResponse classes are defined. The data objects of these classes are available in the API action script. See the example below:

API action

(function (request, response) {
    const reqBody = request.getBody();
    response.setBody({
        "body": JSON.stringify(reqBody),
        "count": 1
    })
})(SimpleApiRequest, SimpleApiResponse)

9. Click Save or Save and exit to apply the changes.
10. You can set API Action Request Parameter related to the action and select the Is required option for any of them if necessary. See the screenshot below:

When sending a request without a mandatory parameter, a user will receive the following message:

{"error":"Required parameter param_1 not sent.","timing":{"before_echo": ...}}

Endpoint call

To call an endpoint, use the following URL format:

https://your_instance_url/v1/api/applicationSlug/module_path/version/action_path?params

Where:

• your_instance_url – the instance URL you use.
• applicationSlug – the value of the Slug field of the application that the endpoint is created for.
• module_path – the value of the Path filed stated in the API Module.
• version – the value of the Path field of the API Version.
• action_path – the value of the Path field stated in the API Action.
• params – the GET parameters.

See below a URL example of calling an endpoint:

https://sandbox-01.dev.simpleone.ru/v1/api/c_simple/api_module_path/api_action_path?param_1=value_1

Authorization

You can make requests to the Scripted REST API with a Bearer token or without any authorization. The type of request authorization depends on the selection of the Is authentication required checkbox on the API action form.

A request to an API action that does not require authorization (Is authentication required=No) is executed under the Guest User:

The requests with an invalid Bearer token are also executed under the Guest User.

To set Basic Auth for request authorization in Scripted REST API, do the following:

1. Set up sending a POST request /v1/auth/login with Basic Auth from an external system to an instance to receive a token.
2. Set up sending a request to the Scripted REST API with the token received in the first step.

Find below the authorization scheme:

This is an example of a server script that uses the Simple API to get a token by sending a POST request with Basic Auth authorization:

Example

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

Supported Content-Type types

To get a request body in a script of API action, call the getBody() method for the request object.

Find below an example script for the API action:

API action

(function (request, response) {
    
    const reqBody = request.getBody();
    const bodyForResponse = typeof reqBody === 'string' ? reqBody : JSON.stringify(reqBody);
    response.setBody({
      "request_body_type": typeof reqBody,
      "request_body": bodyForResponse
    })
    
})(SimpleApiRequest, SimpleApiResponse)

Use the following Content-Type types for the requests sent to the API action:

• application/json
• application/jsonp
• application/xml
• text/xml
• text/html
• text/plain

Send a POST request with a JSON body

---

Send a POST request with an XML body

---

Send a POST request with an HTML body

---

Send a POST request with a text body

---

Response from API action

---

To create a response from the API action, use the response object:

response.setBody({
      "count": 100,
      "status": "OK",
      "error_message": ""
    })

The response of the API action includes a key timing containing the execution time of the API action script:

"timing": {
      "before_echo": 0.0884089469909668
  }