Calling decision services

Your client application calls an endpoint through the decision runtime REST API to execute a decision service. The client calls the decision service by using the standard HTTP GET and POST commands that the web browsers use when they interact with remote servers.

A client application calls a decision service by creating a secure connection with a server, and then calling the decision service through the REST API.

For further information:
Sections in this topic:

Using API keys

To call the decision runtime REST API, you must authenticate it by setting the HTTP header apikey to the API key. For more information about creating API keys, see Creating API keys External link opens a new window or tab.

Endpoint to execute with a decision ID (decisionId)

The endpoint URI for a decision service uses the following format:
POST https://<hostname>:<port>/ads/runtime/api/v1/deploymentSpaces/{deploymentSpaceId}/decisions/{decisionId}/operations/{operation}/extendedExecute
  • <hostname> is the hostname of the decision runtime.
  • <port> is the port of the decision runtime.
Table 1. Parameters that are used in the endpoint URI
Parameter Mandatory or Optional Description
deploymentSpaceId Mandatory

URL encoded identifier that uniquely identifies the place where a decision was deployed.

For more information, see Decision service metadata.
decisionId Mandatory

URL encoded identifier that uniquely identifies a decision to execute.

For more information, see Decision service metadata.

If you are using the run service, you can view the value of decisionId in the Deploy tab in Decision Designer. For more information, see Building and deploying from Decision Designer.
operation Mandatory

Name of the operation. It is used to identify which decision service to execute within the decision service archive.

The operation name is decided at authoring time.

Endpoint to execute the last deployed version of a decision service

The endpoint URI that selects a decision service based on their last deployment time uses the following format:
POST https://<hostname>:<port>/ads/runtime/api/v1/selectors/lastDeployedDecisionService/deploymentSpaces/{deploymentSpaceId}/operations/{operation}/extendedExecute?decisionServiceId={decisionServiceId}

The deployment time of a decision service refers to the deploymentTime metadata of the decision service.

  • <hostname> is the hostname of the decision runtime.
  • <port> is the port of the decision runtime.
Table 2. Parameters that are used in the endpoint URI
Parameter Mandatory or Optional Description
deploymentSpaceId Mandatory URL encoded identifier that uniquely identifies the place where a decision was deployed.
operation Mandatory

Name of the operation. It is used to identify which decision service to execute within the decision service archive.

The operation name is decided at authoring time.
decisionServiceId Mandatory

Query parameter that identifies the decision service from which the decision service archive is built.

The decision service ID is decided at authoring time. Its value is that of the decisionServiceId metadata of the decision service.

For more information about how to view decisionServiceId, see Decision service metadata.

Endpoint to execute the last semantic version of a decision service

The endpoint URI that selects a decision service based on their last semantic version uses the following format.

Extended execution:
POST https://<hostname>:<port>/ads/runtime/api/v1/selectors/lastSemanticDecisionServiceVersion/deploymentSpaces/{deploymentSpaceId}/operations/{operation}/extendedExecute
Simple execution with simplified input and output payloads:
POST https://<hostname>:<port>/ads/runtime/api/v1/selectors/lastSemanticDecisionServiceVersion/deploymentSpaces/{deploymentSpaceId}/operations/{operation}/execute
  • <hostname> is the hostname of the decision runtime.
  • <port> is the port of the decision runtime.
Table 3. Parameters that are used in the endpoint URI
Parameter Mandatory or Optional Description
deploymentSpaceId Mandatory

URL encoded identifier that uniquely identifies the place where a decision was deployed.
operation Mandatory

Name of the operation. It is used to identify which decision service to execute within the decision service archive.

The operation name is decided at authoring time.
decisionServiceId Mandatory

Query parameter that identifies the decision service from which the decision service archive is built.

The decision service ID is decided at authoring time. Its value is that of the decisionServiceId metadata of the decision service.
majorVersion Optional

Query parameter that identifies the major version number of the decision service.

For more information about semantic versions, see Executing the last semantic version.
minorVersion Optional

Query parameter that identifies the minor version number of the decision service.

Endpoint to execute a specific version of a decision service

The endpoint URI that selects a specific version of a decision service uses the following format:
POST https://<hostname>:<port>/ads/runtime/api/v1/selectors/decisionServiceVersion/deploymentSpaces/{deploymentSpaceId}/operations/{operation}/extendedExecute?decisionServiceId={decisionServiceId}&decisionServiceVersion={decisionServiceVersion}
  • <hostname> is the hostname of the decision runtime.
  • <port> is the port of the decision runtime.
Table 4. Parameters that are used in the endpoint URI
Parameter Mandatory or Optional Description
deploymentSpaceId Mandatory

URL encoded identifier that uniquely identifies the place where a decision was deployed.
operation Mandatory

Name of the operation. It is used to identify which decision service to execute within the decision service archive.

The operation name is decided at authoring time.
decisionServiceId Mandatory

Query parameter that identifies the decision service from which the decision service archive is built.

The decision service ID is decided at authoring time. Its value is that of the decisionServiceId metadata of the decision service.
decisionServiceVersion Mandatory

Query parameter that identifies the version of the decision service.

Its value is that of the decisionServiceVersion metadata of the decision service.

Request body

You can use the decision runtime REST API to call decisions by using the JSON payload.

The request body has the following format:
{
  "executionId": "<value_1>",
  "input": "<value_2>",
  "executionTraceFilters": { ... }
}
Table 5. Parameters that are used in the request body
Parameter Mandatory or Optional Description
executionId Optional

Optional identifier for the execution of the decision service.

If this parameter is not set, the decision runtime creates a decision execution identifier that is globally unique.
input Mandatory

JSON object that represents input data of the decision service.

The JSON object can be obtained from the Run part in Decision Designer by editing the JSON data set.
executionTraceFilters Optional

JSON object that specifies which traces are activated in which format.

If this parameter is not set, the execution trace is null as a result.

For more information about getting execution traces, see Execution trace for decision runtime.
An example of the request body:
{
  "executionId": "executionId_0001",
  "input": {
    "customer": {
      "name": "Mary",
      "age": 20
    },
    "ageLimit": 21
  },
  "executionTraceFilters": {
    "executionDuration": true,
    "printedMessages": true,
    "decisionModel": {
      "inputParameters": "Object",
      "outputParameters": "Object",
      "inputNode": "Object",
      "outputNode": "Object"
    },
    "rules": {
      "boundObjectsAtStart": "Object",
      "boundObjectsAtEnd": "Object",
      "allRules": true,
      "executedRules": true,
      "nonExecutedRules": true
    },
    "ruleflow": {
      "allTasks": false,
      "executedTasks": false,
      "notExecutedTasks": false,
      "selectedRules": false
    }
  }
}

HTTP return codes and execution results

When your client application calls a decision service, you get an HTTP return code. The response body is formatted in JSON payload.

Table 6. HTTP return codes
HTTP return code Description
200

The decision operation was successfully executed.

The output of the decision is returned in the response body.
400

The decision operation could not be executed due to a problem in the input payload.
401

The decision operation could not be performed due to an authentication problem.
403

No sufficient privileges to execute the decision.
404

The decision service or decision operation was not found.
500

The decision operation could not be performed due to an internal error.
The JSON body of the response has the following format:
{
  "decisionId": "<value_5>",
  "decisionOperation": "<value_6>",
  "executionId": "<value_7>",
  "executionTrace": "<value_8>",
  "output": "<value_9>",
  "incident": {
    "incidentID": "<incident_ID>",
    "incidentCategory": "<error_message>",
    "stackTrace": "<xyzException>:<stack_message>"
  }
}
  • executionTrace might be null if no execution trace filter is set.
  • output might be null if the execution is not completed due to an error.
  • incident is returned only when errors occur.
For more information about the execution trace and the incident, see the Schema section in the Decision runtime REST API reference in Reference.
The following example shows a response body with the HTTP return code 200 (the execution was successful):
{
  "decisionId": "decisions/My-Getting-Started/mySalutationDecisionService/1.0.0-SNAPSHOT/mySalutationDecisionService-1.0.0-20200120.153649-11.jar",
  "decisionOperation": "myModel",
  "executionId": "24543a29-ce83-4e20-afbc-93fccf7949d5",
  "executionTrace": null,
  "output": "Good evening Prof. Jones!"
}
The following example shows a response body with the HTTP return code 500 (the execution failed):
{
  "decisionId": "decisions/My-Getting-Started/mySalutationDecisionService/1.0.0-SNAPSHOT/mySalutationDecisionService-1.0.0-20200120.153649-11.jar",
  "decisionOperation": "myModel",
  "executionId": "1f10653a-c21f-4653-854e-c6e56da4bdaf",
  "executionTrace": null,
  "output": null,
  "incident": {
    "incidentId": "edee977a-5d2e-47ca-b31e-4e866649016c",
    "incidentCategory": "Decision error",
    "stackTrace": "com.fasterxml.jackson.databind.exc.UnrecognizedPropertyException: Unrecognized field \"nme\" (class newtype),  ...  }
}