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.
Role required: admin.
Endpoint setting
To set an endpoint, complete the steps below:
- Create an API Module. Navigate to Scripted REST API→ API Modules.
Specify the Name, Active and Path fields.
- Click Save or Save and exit to apply the changes. A related record API Version is created and located in the Related list.
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 list if needed.
In the Related list area, select the API Action tab and click New.
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.
Fill in the Name and the Path fields. The example value of the Path field is tickets-count.
- In the HTTP Method field, specify the method to call the action.
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)- Click Save or Save and exit to apply the changes.
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:
- Set up sending a POST request /v1/auth/login with Basic Auth from an external system to an instance to receive a token.
- 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:
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:
(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
}
