Scenario execution with API
Scenarios can be executed not only by
other scenarios
in FORMS on the Scoring.one web portal (see section Forms in Sidebar menu overview)
using API by any other software.
Here, we are going to focus on the last method. Using API is allows external services to execute scenario in a popular HTTP request format. There are three ways of executing scenarios via API:
synchronous - execute single scenario and wait for the result
asynchronous - execute single scenario, do something else, get the result when ready
batch - send multiple task for multiple scenarios as a single request and receive individual results
Synchronous scenario execution
Detailed documentation can be found here: https://developer.algolytics.pl/api-details#api=scoring-one-rest-api-documentation&operation=handleRemoteScorePost
Example request:
POST https://api.algolytics.pl/scoringone/api/scenario/code/remote/score?name=testowy&key=65cd4409-b7f3-48b8-9675-d36c72d9f430 HTTP/1.1
Content-Type: application/json
Cache-Control: no-cache
{
"a": "100"
}where testowy is the name of scenario and a key value 65cd4409-b7f3-48b8-9675-d36c72d9f430 is a dummy value for Scoring.One service token. A token can be found in User Settings in the main menu. A payload of the POST request is in our example a single variable "a", which is equal to "100". The names and values of variables in a payload should match variable names expected by the scenario.
Example requests in many formats (HTTP, C#, Curl, Java, JavaScript, PHP, Python, Ruby, Swift) can be found on the documentation.
Example response contains metadata related to the process of reqeust execution, e.g. content-type, date and result of the scenario.
Asynchronous scenario execution
Another option is to call scenario asynchronously. A POST request is send to specify what is to be computed and then GET request is used to retrieve the results.
Example POST request:
POST https://api.algolytics.pl/scoringone/api/scenario/code/scoreasync/testowy HTTP/1.1
Score-Token: xxxxxxxxxxxxxxxxxxxxxxxxx
X-SCE-RequestId: id_12345
X-SCE-CallbackUrl: http://echo.jsontest.com
X-SCE-CallbackRetryCount: 3
X-SCE-CallbackRetryDelay: 30
Content-Type: application/json
Cache-Control: no-cache
{
"a": "123"
}Example GET request:
GET https://api.algolytics.pl/scoringone/api/scenario/code/scoreasyncresult/testowy HTTP/1.1
X-SCE-RequestId: id_12345
Cache-Control: no-cache
Score-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxMore details in documentation for POST and GET requests.
Batch scenario execution
This option is used to run a scenario multiple times with different input data. The procedure consists of three steps:
Send a batch of data; receive an identifier of a batch
Check if the data is processed; receive a list of identifiers of individual results
Get individual results
Each step has a dedicated endpoint. An example of sending a two element batch is presented below.
POST https://api.algolytics.pl/scoringone/api/batch/score?key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxx HTTP/1.1
Content-Type: application/json
Cache-Control: no-cache
{
"scenarioName": "testowy",
"parameters": [
{"a": "123"},
{"a": "456"}
]
}(More about this request: https://developer.algolytics.pl/api-details#api=scoring-one-rest-api-documentation&operation=getTestsCases)
The payload of this request requires two fields:
scenarioName - scenario name to be executed
parameters - a list of objects with input parameters for the scenario
In response we should obtain batchTaskId which identifies our batch. It is then used to send another request, which checks whether the results are ready.
GET https://api.algolytics.pl/scoringone/api/batch/65cd4409-b7f3-48b8-9675-d36c72d9f430?key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx HTTP/1.1
Cache-Control: no-cache(More about this request: https://developer.algolytics.pl/api-details#api=scoring-one-rest-api-documentation&operation=getTestsCases_1)
Here, the value 65cd4409-b7f3-48b8-9675-d36c72d9f430 is an example value of batchTaskId. This time we should receive a list resultsIds containing identifiers of the results for every scenario in the batch, in the same order as in the batch. As long as all scenarios from the batch are not finished, the returned list resultsIds will be empty. If any scenario crashes during execution, it will not harm the whole batch, just the error message will be instead of the results. To download the results, for each id in the list we need to make the following request:
GET https://api.algolytics.pl/scoringone/api/scenario/code/scoreasyncresult/testowy HTTP/1.1
X-SCE-RequestId: id
Cache-Control: no-cache
Score-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxx(More about this request: https://developer.algolytics.pl/api-details#api=scoring-one-rest-api-documentation&operation=handleScoreAsync_1)
A trick to run multiple different scenarios
The procedure described above requires that the batch consists of a list of the same scenarios, which differ in arguments only. What if we want to send different scenarios?
We can create a wrapping scenario, which will run any other scenario inside. Let's name the scenario scenario_wrapper which takes two input arguments: scenario_name, scenario_input. Then, a request sending a batch to server will look like this
POST https://api.algolytics.pl/scoringone/api/batch/score?key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxx HTTP/1.1
Content-Type: application/json
Cache-Control: no-cache
{
"scenarioName": "scenario_wrapper",
"parameters": [
{"scenario_name": "testowy", "scenario_input": {"a":"123"}},
{"scenario_name": "other_scenario", "scenario_input": {"name":"John", "age": "30"}}
]
}Although we can run multiple different scenarios in this way, it may not be optimal. If some scenarios require much more time than the others, we will wait for the results until the most time consuming scenario is finished.
Last updated