第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.properties
and~/application-users.properties
.To add a user with the
kie-server
role, navigate to~/$SERVER_HOME/bin
and run the following command:$ ./add-user.sh -a --user <USERNAME> --password <PASSWORD> --role kie-server
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 yourPOST
orPUT
API request data:-
application/json
(JSON) -
application/xml
(XML, for JAXB or XSTREAM)
-
X-KIE-ContentType
: Required header forapplication/xml
XSTREAM 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=STARTED
HTTP
POST
andPUT
requests 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-id
{ "release-id": { "artifact-id": "Project1", "group-id": "com.redhat", "version": "1.1" } }
21.1. Sending requests with the KIE Server REST API using a REST client or curl utility
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-server
user role access to KIE Server.
Procedure
-
Identify the relevant API endpoint to which you want to send a request, such as
[GET] /server/containers
to retrieve KIE containers from KIE Server. In a REST client or curl utility, enter the following components for a
GET
request 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-server
role. 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-server
role. -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"
-
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):
{ "type": "SUCCESS", "msg": "List of created containers", "result": { "kie-containers": { "kie-container": [ { "container-id": "itorders_1.0.0-SNAPSHOT", "release-id": { "group-id": "itorders", "artifact-id": "itorders", "version": "1.0.0-SNAPSHOT" }, "resolved-release-id": { "group-id": "itorders", "artifact-id": "itorders", "version": "1.0.0-SNAPSHOT" }, "status": "STARTED", "scanner": { "status": "DISPOSED", "poll-interval": null }, "config-items": [], "container-alias": "itorders" } ] } } }
-
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
PUT
request 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-server
role. HTTP Headers: Set the following headers:
-
Accept
:application/json
Content-Type
:application/json
注記When you add
fields=not_null
toContent-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:
{ "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" } }
For curl utility:
-
-u
: Enter the user name and password of the KIE Server user with thekie-server
role. -H
: Set the following headers:-
Accept
:application/json
Content-Type
:application/json
注記When you add
fields=not_null
toContent-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 @my-container-configs.json
-
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):
{ "type": "SUCCESS", "msg": "Container MyContainer successfully deployed with module itorders:itorders:1.0.0-SNAPSHOT.", "result": { "kie-container": { "container-id": "MyContainer", "release-id": { "group-id": "itorders", "artifact-id": "itorders", "version": "1.0.0-SNAPSHOT" }, "resolved-release-id": { "group-id": "itorders", "artifact-id": "itorders", "version": "1.0.0-SNAPSHOT" }, "status": "STARTED", "scanner": { "status": "STARTED", "poll-interval": 5000 }, "config-items": [], "messages": [ { "severity": "INFO", "timestamp": { "java.util.Date": 1540584717937 }, "content": [ "Container MyContainer successfully created with module itorders:itorders:1.0.0-SNAPSHOT." ] } ], "container-alias": null } } }
If you encounter request errors, review the returned error code messages and adjust your request accordingly.