About DMN endpoints on Kogito

04 August 2020

This post summarises the current design of REST endpoints which are automatically generated and made available, when using DMN model assets in a Kogito application. This work was finalised as part of KOGITO-2840.

Introduction

For each DMN model in a Kogito application, a collection of REST endpoints is automatically code generated based on the content of the model.

For each DMN model there will be:

• one REST “business-domain” endpoint to support the evaluation of the whole model
• one REST “business-domain” endpoint to support the evaluation for each Decision Service(s) in the model

and also analogous endpoints returning classic DMNResult comprising business domain context and helper messages and helper decision “pointers”:

• one REST “dmnresult” endpoint to support the evaluation of the whole model
• one REST “dmnresult” endpoint to support the evaluation for each Decision Service(s) in the model

and finally:

• one REST GET to return the DMN xml without decision-logic
  This can be helpful for model introspection.
  We are planning to eventually parametrise this endpoint with additional options for TrustyAI.

URL naming

The naming of the endpoints is currently structured with the following convention:

POST

• {modelname}
• {modelname}/{decisionServiceName}
• {modelname}/dmnresult
• {modelname}/{decisionServiceName}/dmnresult

GET

• {modelname}

Choosing between “business-domain” and dmnresult variant of the REST endpoints

If a client application is only concerned with a positive evaluation outcome, is not interested in parsing Info/Warn message(s) and only needs to get an http 5xx in case of Errors, might prefer to opt for using the “business-domain” variant. Especially the feature of singleton coercion of Decision Service result, mimicking the DMN modeling behaviour, might be helpful for single page application-like clients.

If a client needs to parse also Info/Warn/Error messages in all the cases, it is best to prefer the dmnresult variant.

API details of the “business-domain” endpoints

The whole model endpoint needs as the input payload, all the Input Data of the model.

Once invoked, the output payload will be the resulting DMN context of the whole model evaluation, that is the one composed of the actual resulting Decision values, the original input values, and all other parametric DRG requirements in serialized form (e.g.: a BKM will be available in string serialized form in its signature).

The decision service endpoint needs as the input payload, all the requirements of the Decision Service.

Once invoked, the output payload will be the resulting DMN context of the Decision Service evaluation, that is the one composed of the actual resulting Decision values, the original input requirements, and all other parametric DRG requirements in serialized form (e.g.: a BKM will be available in string serialized form in its signature).

In the case the Decision Service is composed of a single output decision, the output payload will be the resulting value of that specific Decision; this is to provide an equivalent at API level of a specification feature, when invoking the Decision Service in the model itself. This feature can be used for example to interact very easily from single page web applications, with a DMN Decision Service.

For all these endpoints, in case of a DMN evaluation Error, a full DMNResult payload is returned along with a http 5xx error. In case of a DMN Info/Warn message, these will be returned along with the “business-domain” return rest payload, in the X-Kogito-decision-messages extended http header, more as an helper than to be used for client-side business logic; this is based on the assumption that, in case when more refined client-side business logic is required, the client can actually use the “dmnresult” variant of the endpoints.

Examples

In the following sections, some basic examples will be presented.

Endpoint: whole model 

Given:

We notice the name of the DMN model is Traffic Violation:

endpoint: localhost:8080/Traffic Violation

input payload:

{
    "Driver": {
        "Points": 2
    },
    "Violation": {
        "Type": "speed",
        "Actual Speed": 120,
        "Speed Limit": 100
    }
}

output:

{
  "Violation": {
    "Type": "speed",
    "Speed Limit": 100,
    "Actual Speed": 120
  },
  "Driver": {
    "Points": 2
  },
  "Fine": {
    "Points": 3,
    "Amount": 500
  },
  "Should the driver be suspended?": "No"
}

Endpoint: decision service with singleton output decision

Given:

we notice the name of the decision service is TrafficViolationDecisionService:

endpoint: localhost:8080/Traffic Violation/TrafficViolationDecisionService

input payload:

{
    "Driver": {
        "Points": 2
    },
    "Violation": {
        "Type": "speed",
        "Actual Speed": 120,
        "Speed Limit": 100
    }
}

output:

"No"

Endpoint: decision service with multiple output decision

Now given instead:

endpoint: localhost:8080/Traffic Violation/TrafficViolationDecisionService

input payload:

{
    "Driver": {
        "Points": 2
    },
    "Violation": {
        "Type": "speed",
        "Actual Speed": 120,
        "Speed Limit": 100
    }
}

output:

{
    "Violation": {
        "Type": "speed",
        "Speed Limit": 100,
        "Actual Speed": 120
    },
    "Driver": {
        "Points": 2
    },
    "Fine": {
        "Points": 3,
        "Amount": 500
    },
    "Should the driver be suspended?": "No"
}

Conclusions

We have seen the current design of DMN REST endpoints automatically generated in a Kogito application and how can be used to support several use-cases.

We like to hear your feedback! Do you have some thoughts or question about this topic? Please make sure to let us know!