此内容没有您所选择的语言版本。
Chapter 21. KIE Server REST API for KIE containers and business assets
Red Hat Decision Manager provides a KIE Server REST API that you can use to interact with your KIE containers and business assets (such as business rules, processes, and solvers) in Red Hat Decision Manager without using the Business Central user interface. This API support enables you to maintain your Red Hat Decision Manager resources more efficiently and optimize your integration and development with Red Hat Decision Manager.
With the KIE Server REST API, you can perform the following actions:
- Deploy or dispose KIE containers
- Retrieve and update KIE container information
- Return KIE Server status and basic information
- Retrieve and update business asset information
- Execute business assets (such as rules and processes)
KIE Server REST API requests require the following components:
- Authentication
The KIE Server REST API requires HTTP Basic authentication or token-based authentication for the user role
kie-server. To view configured user roles for your Red Hat Decision Manager distribution, navigate to~/$SERVER_HOME/standalone/configuration/application-roles.propertiesand~/application-users.properties.To add a user with the
kie-serverrole, navigate to~/$SERVER_HOME/binand run the following command:./bin/jboss-cli.sh --commands="embed-server --std-out=echo,/subsystem=elytron/filesystem-realm=ApplicationRealm:add-identity(identity=<USERNAME>),/subsystem=elytron/filesystem-realm=ApplicationRealm:set-password(identity=<USERNAME>, clear={password='<PASSWORD>'}),/subsystem=elytron/filesystem-realm=ApplicationRealm:add-identity-attribute(identity=<USERNAME>, name=role, value=['kie-server'])"$ ./bin/jboss-cli.sh --commands="embed-server --std-out=echo,/subsystem=elytron/filesystem-realm=ApplicationRealm:add-identity(identity=<USERNAME>),/subsystem=elytron/filesystem-realm=ApplicationRealm:set-password(identity=<USERNAME>, clear={password='<PASSWORD>'}),/subsystem=elytron/filesystem-realm=ApplicationRealm:add-identity-attribute(identity=<USERNAME>, name=role, value=['kie-server'])"Copy to Clipboard Copied! Toggle word wrap Toggle overflow For more information about user roles and Red Hat Decision Manager installation options, see Planning a Red Hat Decision Manager installation.
- HTTP headers
The KIE Server REST API requires the following HTTP headers for API requests:
Accept: Data format accepted by your requesting client:-
application/json(JSON) -
application/xml(XML, for JAXB or XSTREAM)
-
Content-Type: Data format of yourPOSTorPUTAPI request data:-
application/json(JSON) -
application/xml(XML, for JAXB or XSTREAM)
-
X-KIE-ContentType: Required header forapplication/xmlXSTREAM API requests and responses:-
XSTREAM
-
- HTTP methods
The KIE Server REST API supports the following HTTP methods for API requests:
-
GET: Retrieves specified information from a specified resource endpoint -
POST: Updates a resource or resource instance -
PUT: Updates or creates a resource or resource instance -
DELETE: Deletes a resource or resource instance
-
- Base URL
-
The base URL for KIE Server REST API requests is
http://SERVER:PORT/kie-server/services/rest/, such ashttp://localhost:8080/kie-server/services/rest/. - Endpoints
KIE Server REST API endpoints, such as
/server/containers/{containerId}for a specified KIE container, are the URIs that you append to the KIE Server REST API base URL to access the corresponding resource or type of resource in Red Hat Decision Manager.Example request URL for
/server/containers/{containerId}endpointhttp://localhost:8080/kie-server/services/rest/server/containers/MyContainer- Request parameters and request data
Many KIE Server REST API requests require specific parameters in the request URL path to identify or filter specific resources and to perform specific actions. You can append URL parameters to the endpoint in the format
?<PARAM>=<VALUE>&<PARAM>=<VALUE>.Example GET request URL with parameters
http://localhost:8080/kie-server/services/rest/server/containers?groupId=com.redhat&artifactId=Project1&version=1.0&status=STARTEDHTTP
POSTandPUTrequests may additionally require a request body or file with data to accompany the request.Example POST request URL and JSON request body data
http://localhost:8080/kie-server/services/rest/server/containers/MyContainer/release-idCopy to Clipboard Copied! Toggle word wrap Toggle overflow
The KIE Server REST API enables you to interact with your KIE containers and business assets (such as business rules, processes, and solvers) in Red Hat Decision Manager without using the Business Central user interface. You can send KIE Server REST API requests using any REST client or curl utility.
Prerequisites
- KIE Server is installed and running.
-
You have
kie-serveruser role access to KIE Server.
Procedure
-
Identify the relevant API endpoint to which you want to send a request, such as
[GET] /server/containersto retrieve KIE containers from KIE Server. In a REST client or curl utility, enter the following components for a
GETrequest to/server/containers. Adjust any request details according to your use case.For REST client:
-
Authentication: Enter the user name and password of the KIE Server user with the
kie-serverrole. HTTP Headers: Set the following header:
-
Accept:application/json
-
-
HTTP method: Set to
GET. -
URL: Enter the KIE Server REST API base URL and endpoint, such as
http://localhost:8080/kie-server/services/rest/server/containers.
For curl utility:
-
-u: Enter the user name and password of the KIE Server user with thekie-serverrole. -H: Set the following header:-
Accept:application/json
-
-
-X: Set toGET. -
URL: Enter the KIE Server REST API base URL and endpoint, such as
http://localhost:8080/kie-server/services/rest/server/containers.
curl -u 'baAdmin:password@1' -H "Accept: application/json" -X GET "http://localhost:8080/kie-server/services/rest/server/containers"
curl -u 'baAdmin:password@1' -H "Accept: application/json" -X GET "http://localhost:8080/kie-server/services/rest/server/containers"Copy to Clipboard Copied! Toggle word wrap Toggle overflow -
Authentication: Enter the user name and password of the KIE Server user with the
Execute the request and review the KIE Server response.
Example server response (JSON):
Copy to Clipboard Copied! Toggle word wrap Toggle overflow -
For this example, copy or note the project
group-id,artifact-id, andversion(GAV) data from one of the deployed KIE containers returned in the response. In your REST client or curl utility, send another API request with the following components for a
PUTrequest to/server/containers/{containerId}to deploy a new KIE container with the copied project GAV data. Adjust any request details according to your use case.For REST client:
-
Authentication: Enter the user name and password of the KIE Server user with the
kie-serverrole. HTTP Headers: Set the following headers:
-
Accept:application/json Content-Type:application/jsonNoteWhen you add
fields=not_nulltoContent-Type, the null fields are excluded from the REST API response.
-
-
HTTP method: Set to
PUT. -
URL: Enter the KIE Server REST API base URL and endpoint, such as
http://localhost:8080/kie-server/services/rest/server/containers/MyContainer. - Request body: Add a JSON request body with the configuration items for the new KIE container:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow For curl utility:
-
-u: Enter the user name and password of the KIE Server user with thekie-serverrole. -H: Set the following headers:-
Accept:application/json Content-Type:application/jsonNoteWhen you add
fields=not_nulltoContent-Type, the null fields are excluded from the REST API response.
-
-
-X: Set toPUT. -
URL: Enter the KIE Server REST API base URL and endpoint, such as
http://localhost:8080/kie-server/services/rest/server/containers/MyContainer. -
-d: Add a JSON request body or file (@file.json) with the configuration items for the new KIE container:
curl -u 'baAdmin:password@1' -H "Accept: application/json" -H "Content-Type: application/json" -X PUT "http://localhost:8080/kie-server/services/rest/server/containers/MyContainer" -d "{ \"config-items\": [ { \"itemName\": \"RuntimeStrategy\", \"itemValue\": \"SINGLETON\", \"itemType\": \"java.lang.String\" }, { \"itemName\": \"MergeMode\", \"itemValue\": \"MERGE_COLLECTIONS\", \"itemType\": \"java.lang.String\" }, { \"itemName\": \"KBase\", \"itemValue\": \"\", \"itemType\": \"java.lang.String\" }, { \"itemName\": \"KSession\", \"itemValue\": \"\", \"itemType\": \"java.lang.String\" } ], \"release-id\": { \"group-id\": \"itorders\", \"artifact-id\": \"itorders\", \"version\": \"1.0.0-SNAPSHOT\" }, \"scanner\": { \"poll-interval\": \"5000\", \"status\": \"STARTED\" }}"curl -u 'baAdmin:password@1' -H "Accept: application/json" -H "Content-Type: application/json" -X PUT "http://localhost:8080/kie-server/services/rest/server/containers/MyContainer" -d "{ \"config-items\": [ { \"itemName\": \"RuntimeStrategy\", \"itemValue\": \"SINGLETON\", \"itemType\": \"java.lang.String\" }, { \"itemName\": \"MergeMode\", \"itemValue\": \"MERGE_COLLECTIONS\", \"itemType\": \"java.lang.String\" }, { \"itemName\": \"KBase\", \"itemValue\": \"\", \"itemType\": \"java.lang.String\" }, { \"itemName\": \"KSession\", \"itemValue\": \"\", \"itemType\": \"java.lang.String\" } ], \"release-id\": { \"group-id\": \"itorders\", \"artifact-id\": \"itorders\", \"version\": \"1.0.0-SNAPSHOT\" }, \"scanner\": { \"poll-interval\": \"5000\", \"status\": \"STARTED\" }}"Copy to Clipboard Copied! Toggle word wrap Toggle overflow curl -u 'baAdmin:password@1' -H "Accept: application/json" -H "Content-Type: application/json" -X PUT "http://localhost:8080/kie-server/services/rest/server/containers/MyContainer" -d @my-container-configs.json
curl -u 'baAdmin:password@1' -H "Accept: application/json" -H "Content-Type: application/json" -X PUT "http://localhost:8080/kie-server/services/rest/server/containers/MyContainer" -d @my-container-configs.jsonCopy to Clipboard Copied! Toggle word wrap Toggle overflow -
Authentication: Enter the user name and password of the KIE Server user with the
Execute the request and review the KIE Server response.
Example server response (JSON):
Copy to Clipboard Copied! Toggle word wrap Toggle overflow If you encounter request errors, review the returned error code messages and adjust your request accordingly.
The KIE Server REST API supports a Swagger web interface that you can use instead of a standalone REST client or curl utility to interact with your KIE containers and business assets (such as business rules, processes, and solvers) in Red Hat Decision Manager without using the Business Central user interface.
By default, the Swagger web interface for KIE Server is enabled by the org.kie.swagger.server.ext.disabled=false system property. To disable the Swagger web interface in KIE Server, set this system property to true.
Prerequisites
- KIE Server is installed and running.
-
You have
kie-serveruser role access to KIE Server.
Procedure
-
In a web browser, navigate to
http://SERVER:PORT/kie-server/docs, such ashttp://localhost:8080/kie-server/docs, and log in with the user name and password of the KIE Server user with thekie-serverrole. -
In the Swagger page, select the relevant API endpoint to which you want to send a request, such as KIE Server and KIE containers
[GET] /server/containers to retrieve KIE containers from KIE Server. - Click Try it out and provide any optional parameters by which you want to filter results, if needed.
- In the Response content type drop-down menu, select the desired format of the server response, such as application/json for JSON format.
Click Execute and review the KIE Server response.
Example server response (JSON):
Copy to Clipboard Copied! Toggle word wrap Toggle overflow -
For this example, copy or note the project
group-id,artifact-id, andversion(GAV) data from one of the deployed KIE containers returned in the response. -
In the Swagger page, navigate to the KIE Server and KIE containers
[PUT] /server/containers/{containerId} endpoint to send another request to deploy a new KIE container with the copied project GAV data. Adjust any request details according to your use case. Click Try it out and enter the following components for the request:
-
containerId: Enter the ID of the new KIE container, such as
MyContainer. - body: Set the Parameter content type to the desired request body format, such as application/json for JSON format, and add a request body with the configuration items for the new KIE container:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow -
containerId: Enter the ID of the new KIE container, such as
- In the Response content type drop-down menu, select the desired format of the server response, such as application/json for JSON format.
Click Execute and review the KIE Server response.
Example server response (JSON):
Copy to Clipboard Copied! Toggle word wrap Toggle overflow If you encounter request errors, review the returned error code messages and adjust your request accordingly.
21.3. Supported KIE Server REST API endpoints 复制链接链接已复制到粘贴板!
The KIE Server REST API provides endpoints for the following types of resources in Red Hat Decision Manager:
- KIE Server and KIE containers
- KIE session assets (for runtime commands)
- DMN assets
- Planning solvers
The KIE Server REST API base URL is http://SERVER:PORT/kie-server/services/rest/. All requests require HTTP Basic authentication or token-based authentication for the kie-server user role.
For the full list of KIE Server REST API endpoints and descriptions, use one of the following resources:
- Execution Server REST API on the jBPM Documentation page (static)
Swagger UI for the KIE Server REST API at
http://SERVER:PORT/kie-server/docs(dynamic, requires running KIE Server)NoteBy default, the Swagger web interface for KIE Server is enabled by the
org.kie.swagger.server.ext.disabled=falsesystem property. To disable the Swagger web interface in KIE Server, set this system property totrue.
21.3.1. REST endpoints for specific DMN models 复制链接链接已复制到粘贴板!
Red Hat Decision Manager provides model-specific DMN KIE Server endpoints that you can use to interact with your specific DMN model without using the Business Central user interface.
For each DMN model in a container in Red Hat Decision Manager, the following KIE Server REST endpoints are automatically generated based on the content of the DMN model:
-
POST /server/containers/{containerId}/dmn/models/{modelname}: A business-domain endpoint for evaluating a specified DMN model in a container -
POST /server/containers/{containerId}/dmn/models/{modelname}/{decisionServiceName}: A business-domain endpoint for evaluating a specified decision service component in a specific DMN model available in a container -
POST /server/containers/{containerId}/dmn/models/{modelname}/dmnresult: An endpoint for evaluating a specified DMN model containing customized body payload and returning aDMNResultresponse, including business-domain context, helper messages, and helper decision pointers -
POST /server/containers/{containerId}/dmn/models/{modelname}/{decisionServiceName}/dmnresult: An endpoint for evaluating a specified decision service component in a specific DMN model and returning aDMNResultresponse, including the business-domain context, helper messages, and help decision pointers for the decision service -
GET /server/containers/{containerId}/dmn/models/{modelname}: An endpoint for returning standard DMN XML without decision logic and containing the inputs and decisions of the specified DMN model -
GET /server/containers/{containerId}/dmn/openapi.json (|.yaml): An endpoint for retrieving Swagger or OAS for the DMN models in a specified container
You can use these endpoints to interact with a DMN model or a specific decision service within a model. As you decide between using business-domain and dmnresult variants of these REST endpoints, review the following considerations:
-
REST business-domain endpoints: Use this endpoint type if a client application is only concerned with a positive evaluation outcome, is not interested in parsing
InfoorWarnmessages, and only needs an HTTP 5xx response for any errors. This type of endpoint is also helpful for single-page application-like clients, due to singleton coercion of decision service results that resemble the DMN modeling behavior. -
REST
dmnresultendpoints: Use this endpoint type if a client needs to parseInfo,Warn, orErrormessages in all cases.
For each endpoint, use a REST client or curl utility to send requests with the following components:
-
Base URL:
http://HOST:PORT/kie-server/services/rest/ Path parameters:
-
{containerId}: The string identifier of the container, such asmykjar-project -
{modelName}: The string identifier of the DMN model, such asTraffic Violation -
{decisionServiceName}: The string identifier of the decision service component in the DMN DRG, such asTrafficViolationDecisionService -
dmnresult: The string identifier that enables the endpoint to return a fullDMNResultresponse with more detailedInfo,Warn, andErrormessaging
-
HTTP headers: For
POSTrequests only:-
accept:application/json -
content-type:application/json
-
-
HTTP methods:
GETorPOST
The examples in the following endpoints are based on a mykjar-project container that contains a Traffic Violation DMN model, containing a TrafficViolationDecisionService decision service component.
For all of these endpoints, if a DMN evaluation Error message occurs, a DMNResult response is returned along with an HTTP 5xx error. If a DMN Info or Warn message occurs, the relevant response is returned along with the business-domain REST body, in the X-Kogito-decision-messages extended HTTP header, to be used for client-side business logic. When there is a requirement of more refined client-side business logic, the client can use the dmnresult variant of the endpoints.
- Retrieve Swagger or OAS for DMN models in a specified container
GET /server/containers/{containerId}/dmn/openapi.json (|.yaml)Example REST endpoint
http://localhost:8080/kie-server/services/rest/server/containers/mykjar-project/dmn/openapi.json (|.yaml)- Return the DMN XML without decision logic
GET /server/containers/{containerId}/dmn/models/{modelname}Example REST endpoint
http://localhost:8080/kie-server/services/rest/server/containers/mykjar-project/dmn/models/Traffic ViolationExample curl request
curl -u wbadmin:wbadmin -X GET "http://localhost:8080/kie-server/services/rest/server/containers/mykjar-project/dmn/models/Traffic%20Violation" -H "accept: application/xml"
curl -u wbadmin:wbadmin -X GET "http://localhost:8080/kie-server/services/rest/server/containers/mykjar-project/dmn/models/Traffic%20Violation" -H "accept: application/xml"Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example response (XML)
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - Evaluate a specified DMN model in a specified container
POST /server/containers/{containerId}/dmn/models/{modelname}Example REST endpoint
http://localhost:8080/kie-server/services/rest/server/containers/mykjar-project/dmn/models/Traffic ViolationExample curl request
curl -u wbadmin:wbadmin-X POST "http://localhost:8080/kie-server/services/rest/server/containers/mykjar-project/dmn/models/Traffic Violation" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"Driver\":{\"Points\":15},\"Violation\":{\"Date\":\"2021-04-08\",\"Type\":\"speed\",\"Actual Speed\":135,\"Speed Limit\":100}}"curl -u wbadmin:wbadmin-X POST "http://localhost:8080/kie-server/services/rest/server/containers/mykjar-project/dmn/models/Traffic Violation" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"Driver\":{\"Points\":15},\"Violation\":{\"Date\":\"2021-04-08\",\"Type\":\"speed\",\"Actual Speed\":135,\"Speed Limit\":100}}"Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example POST request body with input data
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example response (JSON)
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - Evaluate a specified decision service within a specified DMN model in a container
POST /server/containers/{containerId}/dmn/models/{modelname}/{decisionServiceName}For this endpoint, the request body must contain all the requirements of the decision service. The response is the resulting DMN context of the decision service, including the decision values, the original input values, and all other parametric DRG components in serialized form. For example, a business knowledge model is available in string-serialized form in its signature.
If the decision service is composed of a single-output decision, the response is the resulting value of that specific decision. This behavior provides an equivalent value at the API level of a specification feature when invoking the decision service in the model itself. As a result, you can, for example, interact with a DMN decision service from single-page web applications.
Figure 21.1. Example
TrafficViolationDecisionServicedecision service with single-output decisionFigure 21.2. Example
TrafficViolationDecisionServicedecision service with multiple-output decisionExample REST endpoint
http://localhost:8080/kie-server/services/rest/server/containers/mykjar-project/dmn/models/Traffic Violation/TrafficViolationDecisionServiceExample POST request body with input data
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example curl request
curl -X POST http://localhost:8080/kie-server/services/rest/server/containers/mykjar-project/dmn/models/Traffic Violation/TrafficViolationDecisionService -H 'content-type: application/json' -H 'accept: application/json' -d '{"Driver": {"Points": 2}, "Violation": {"Type": "speed", "Actual Speed": 120, "Speed Limit": 100}}'curl -X POST http://localhost:8080/kie-server/services/rest/server/containers/mykjar-project/dmn/models/Traffic Violation/TrafficViolationDecisionService -H 'content-type: application/json' -H 'accept: application/json' -d '{"Driver": {"Points": 2}, "Violation": {"Type": "speed", "Actual Speed": 120, "Speed Limit": 100}}'Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example response for single-output decision (JSON)
"No"
"No"Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example response for multiple-output decision (JSON)
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - Evaluate a specified DMN model in a specified container and return a
DMNResultresponse POST /server/containers/{containerId}/dmn/models/{modelname}/dmnresultExample REST endpoint
http://localhost:8080/kie-server/services/rest/server/containers/mykjar-project/dmn/models/Traffic Violation/dmnresultExample POST request body with input data
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example curl request
curl -X POST http://localhost:8080/kie-server/services/rest/server/containers/mykjar-project/dmn/models/Traffic Violation/dmnresult -H 'content-type: application/json' -H 'accept: application/json' -d '{"Driver": {"Points": 2}, "Violation": {"Type": "speed", "Actual Speed": 120, "Speed Limit": 100}}'curl -X POST http://localhost:8080/kie-server/services/rest/server/containers/mykjar-project/dmn/models/Traffic Violation/dmnresult -H 'content-type: application/json' -H 'accept: application/json' -d '{"Driver": {"Points": 2}, "Violation": {"Type": "speed", "Actual Speed": 120, "Speed Limit": 100}}'Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example response (JSON)
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - Evaluate a specified decision service within a DMN model in a specified container and return a
DMNResultresponse POST /server/containers/{containerId}/dmn/models/{modelname}/{decisionServiceName}/dmnresultExample REST endpoint
http://localhost:8080/kie-server/services/rest/server/containers/mykjar-project/dmn/models/Traffic Violation/TrafficViolationDecisionService/dmnresultExample POST request body with input data
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example curl request
curl -X POST http://localhost:8080/kie-server/services/rest/server/containers/mykjar-project/dmn/models/Traffic Violation/TrafficViolationDecisionService/dmnresult -H 'content-type: application/json' -H 'accept: application/json' -d '{"Driver": {"Points": 2}, "Violation": {"Type": "speed", "Actual Speed": 120, "Speed Limit": 100}}'curl -X POST http://localhost:8080/kie-server/services/rest/server/containers/mykjar-project/dmn/models/Traffic Violation/TrafficViolationDecisionService/dmnresult -H 'content-type: application/json' -H 'accept: application/json' -d '{"Driver": {"Points": 2}, "Violation": {"Type": "speed", "Actual Speed": 120, "Speed Limit": 100}}'Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example response (JSON)
Copy to Clipboard Copied! Toggle word wrap Toggle overflow