matteomortari.com

NEW model-specific DMN kie-server endpoints

23 March 2021

Modernising kie-server with new and more user-friendly DMN endpoints, better Swagger/OpenAPI documentation, easier JSON-based REST invocations; an intermediate step to help developers transitioning to service-oriented deployments such as a Kogito-based application.

In a nutshell:

The current DMN kie-server endpoints are fully compliant with kie-server extension design architecture, and aligned with all other kie-server services and extensions; however, some aspects of the current generic approach of kie-server sometimes are not very user-friendly for DMN evaluations, due to limitations of swagger documentation and the REST payloads requirements to follow the generic kie-server marshaller protocol. These aspects do apply to all kie-server services, including naturally DMN kie-server endpoints as well.
On other hand, experience shown that building manually the REST payload on Kogito for DMN evaluation is very easy for end-users, thanks to key features pertaining to DMN core capabilities.

This new feature (DROOLS-6047) extends DMN on kie-server with new endpoints, leveraging those core capabilities; the new DMN endpoints provide better Swagger documentation and can be more easily consumed by end-users, therefore contributing to modernising the kie-server platform while also making easier to eventually transition to a full Kogito-based application and deployment!

Why is this needed?

Currently on kie-server, the DMN service exposes 2 endpoints which are fully compliant with kie-server extension design architecture:

The current swagger documentation is agnostic to the actual model content of the knowledge asset, like for any other kie-server extension:

This limited style of swagger documentation is sometimes an undesirable side-effect to the generic approach of kie-server extension design:

About the last point specifically, consider this example DMN payload:

{
       "model-namespace": "https://kiegroup.org/dmn/_FA9849E2-C92E-4E27-83BF-07A7428DC9C9",
       "model-name": "Traffic Violation",
       "dmn-context": {
           "Driver": ...,
           "Violation": ...
       }
    }

because the content of dmn-context depends on the values of model-namespace and model-name coordinates, there is no pragmatic way to define with Swagger/OpenAPI that dmn-context must have the properties “Driver”, “Violation” for this traffic violation model, or property “Customer” for another DMN model.

Besides endpoint documentation limitations, experience proved that building manually from scratch the kie-server generic payload following the style of the kie-server generic marshaller is very difficult for most end-users (in fact we always advise to use the Kie Server Client API first, and not start from scratch, but this suggestion is often ignored anyway):

Example. The correct way to marshall for Traffic Violation example, respecting the domain model defined in the kjar project, would be:

{
       "model-namespace": "https://kiegroup.org/dmn/_FA9849E2-C92E-4E27-83BF-07A7428DC9C9",
       "model-name": "Traffic Violation",
       "dmn-context": {
           "Driver": { "com.acme.Driver" : {
               "Points": 15
           }},
           "Violation": { "com.acme.Violation" : {
               "Type": "speed",
               "Date": "2020-10-01",
               "Actual Speed": 111,
               "Speed Limit": 100
           }}
       }
    }

Everything would be much more easier, while building the JSON body payload manually for DMN evaluation, if we could drop the strict requirement to respect the generic kie-server marshalling format.

NEW model-specific DMN kie-server endpoints

We can now move past and beyond these limitations, thanks to the next generation of DMN endpoints on kie-server, leveraging some new DMN core capabilities:

to ultimately offer more user-friendly endpoints on kie-server for DMN evaluation!

Following similar style to what is offered today via Kogito, summarized in this blog post, we implemented the following new DMN endpoints on kie-server:

  1. GET /server/containers/{containerId}/dmn/openapi.json (|.yaml)
    Retrieves Swagger/OAS for the DMN models in the kjar project
  2. GET /server/containers/{containerId}/dmn/models/{modelname}
    Standard DMN XML but without any decision logic, so this can be used as a descriptor of the DMN model (which are the inputs, which are the decisions), while using the same format of the DMN XSD instead.
  3. POST /server/containers/{containerId}/dmn/models/{modelname}
    JSON-only evaluation of a specific DMN model with a body payload tailored for the specific model
  4. POST /server/containers/{containerId}/dmn/models/{modelname}/{decisionServiceName}
    JSON-only evaluation of a specific decision service of a specific DMN model with a body payload tailored for the specific model
  5. POST /server/containers/{containerId}/dmn/models/{modelname}/dmnresult
    JSON-only evaluation of a specific DMN model with a body payload tailored for the specific model, but returning a JSON representation as a DMNResult
  6. POST /server/containers/{containerId}/dmn/models/{modelname}/{decisionServiceName}/dmnresult
    JSON-only evaluation of a specific decision service of a specific DMN model with a body payload tailored for the specific model, but returning a JSON representation as a DMNResult

For the difference between “business-domain” and “dmnresult” variants of the rest endpoints, reference the original blog post as also linked above.

Making reference to the Traffic Violation example model, this new capability can now offer on kie-server something similar to:

As we can see, both the input body payload and the response body payload offer Swagger/OAS schemas which are consistent with the specific DMN model!

This is possible thanks to a convergence of factors:

Any limitations?

Being a new set of endpoints, in addition to the currently existing ones, there is basically no impact on the already-existing DMN kie-server capabilities.

As this proposed set of new endpoints are contained within a specific {containerId}, it also means that the openapi.json|.yaml swagger/OAS definition file is only kie-container specific.

In turn, it means when accessing the swagger-ui client editor, user need to manually point to the container URL, for example something like:

Finally, as this core capability do leverage Eclipse MicroProfile for OpenAPI Specification (OAS) and SmallRye-openapi-core, this requires making use of Swagger-UI and clients which are compatible with OpenAPI Specification version 3.0.3, onwards.

Conclusions

We believe this feature meaningfully extends the current set of capabilities, by providing more user-friendly DMN endpoints on kie-server!

Developers can make full use of this new feature to simplify existing REST call invocations, and as a stepping stone to eventually migrate to a Kogito-based application.

Have you tried it yet?
Do you have any feedback?
Let us know in the comments below!