10.7. The REST API for Realtime Decision Server Administration

This section provides information about the Rest API for both managed and unmanaged Realtime Decision Server environments. You must set correct HTTP headers for the servers. Refer to The REST API for Realtime Decision Server Execution section for further information about HTTP headers.

10.7.1. Managed Realtime Decision Server Environment

When you have a managed Realtime Decision Server setup, you need to manage Realtime Decision Server and containers through a controller. Usually, it is done through Business Central, but you may also use Controller REST API.
  • The controller base URL is provided by kie-wb war deployment, which is the same as org.kie.server.controller property (for example http://localhost:8080/kie-wb/rest/controller).
  • All requests require basic HTTP Authentication for the role kie-server.
[GET] /admin/servers
Returns a list of Realtime Decision Server instances.

Example 10.8. Example Server Response

<kie-server-instance-list>
  <kie-server-instance>
    <server-id>local-server-123</server-id>
    <server-setup>
      <server-containers>
        <containers container-id="MyContainer" status="STARTED">
          <release-id>
            <artifact-id>project1</artifact-id>
            <group-id>com.sample</group-id>
            <version>1.0.0</version>
          </release-id>
        </containers>
      </server-containers>
    </server-setup>
    <server-managed-instances>
      <managedInstances>
        <location>http://localhost:8080/kie-server/services/rest/server</location>
        <status>UP</status>
        <capabilities>
          <capabilities>KieServer</capabilities>
          <capabilities>BRM</capabilities>
          <capabilities>BPM</capabilities>
        </capabilities>
      </managedInstances>
    </server-managed-instances>
    <server-name>local-server-123</server-name>
    <server-status>UP</server-status>
    <server-version>6.3.0.Final</server-version>
  </kie-server-instance>
</kie-server-instance-list>
[GET] /admin/server/{id}
Returns a Realtime Decision Server instance.

Example 10.9. Server Response

<kie-server-instance>
  <server-id>local-server-123</server-id>
  <server-setup>
    <server-containers>
      <containers container-id="MyContainer" status="STARTED">
        <release-id>
          <artifact-id>project1</artifact-id>
          <group-id>com.sample</group-id>
          <version>1.0.0</version>
        </release-id>
      </containers>
    </server-containers>
  </server-setup>
  <server-managed-instances>
    <managedInstances>
      <location>http://localhost:8080/kie-server/services/rest/server</location>
      <status>UP</status>
      <capabilities>
        <capabilities>KieServer</capabilities>
        <capabilities>BRM</capabilities>
        <capabilities>BPM</capabilities>
      </capabilities>
    </managedInstances>
  </server-managed-instances>
  <server-name>local-server-123</server-name>
  <server-status>UP</server-status>
  <server-version>6.3.0.Final</server-version>
</kie-server-instance>
[PUT] /admin/server/{id}
Creates a new Realtime Decision Server instance with the specified id.

Example 10.10. Example Request to Create a New Realtime Decision Server Instance

<kie-server-info>
  <capabilities>KieServer</capabilities>
  <capabilities>BRM</capabilities>
  <location>http://localhost:8080/kie-server/services/rest/server</location>
  <name>local-server-456</name>
  <id>local-server-456</id>
  <version>6.3.0.Final</version>
</kie-server-info>
[DELETE] /admin/server/{id}
Deletes a Realtime Decision Server instance with the specified id.
[GET] /admin/server/{id}/containers/{containerId}
Returns the container information including its release id.

Example 10.11. Server Response

<kie-container container-id="MyContainer" status="STARTED">
  <release-id>
    <artifact-id>project1</artifact-id>
    <group-id>com.sample</group-id>
    <version>1.0.0</version>
  </release-id>
</kie-container>
[PUT] /admin/server/{id}/containers/{containerId}
Creates a new container with the specified containerId and the given release id.

Example 10.12. Server Request

<kie-container container-id="MyContainer">
  <release-id>
    <artifact-id>project1</artifact-id>
    <group-id>com.sample</group-id>
    <version>1.0.0</version>
  </release-id>
</kie-container>
[DELETE] /admin/server/{id}/containers/{containerId}
Disposes a container with the specified containerId.
[POST] /admin/server/{id}/containers/{containerId}/status/started
Starts the container. No request body required.
[POST] /admin/server/{id}/containers/{containerId}/status/stopped
Stops the Container. No request body required.

10.7.2. Unmanaged Realtime Decision Server Environment

The execution server supports the following commands through the REST API. Note the following before using these commands:
  • The base URL for these will remain as the endpoint defined earlier (http://SERVER:PORT/kie-server/services/rest/server/).
  • All requests require basic HTTP Authentication for the role kie-server.
[GET] /
Returns the execution server information.

Example 10.13. Server Response

<response type="SUCCESS" msg="KIE Server info">
  <kie-server-info>
    <version>6.2.0.redhat-1</version>
  </kie-server-info>
</response>
[POST] /config
Using POST HTTP method, you can execute various commands on the execution server, for example: create-container, list-containers, dispose-container and call-container. Following is the list of supported commands:
  • CreateContainerCommand
  • GetServerInfoCommand
  • ListContainersCommand
  • CallContainerCommand
  • DisposeContainerCommand
  • GetContainerInfoCommand
  • GetScannerInfoCommand
  • UpdateScannerCommand
  • UpdateReleaseIdCommand
For more information about the commands, see the org.kie.server.api.commands package.

Example 10.14. Request to Create a Container

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<script>
	<create-container>
		<container container-id="command-script-container">
			<release-id>
				<artifact-id>baz</artifact-id>
				<group-id>foo.bar</group-id>
				<version>2.1.0.GA</version>
			</release-id>
		</container>
	</create-container>
	<call-container container-id="command-script-container">
		<payload><?xml version="1.0" encoding="UTF-8" standalone="yes"?>
			<batch-execution lookup="defaultKieSession">
				<insert out-identifier="message" return-object="true" entry-point="DEFAULT" disconnected="false">
					<object xsi:type="message" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
						<text>HelloWorld</text>
					</object>
				</insert>
				<fire-all-rules max="-1"/>
			</batch-execution>
		</payload>
	</call-container>
	<dispose-container container-id="command-script-container"/>
</script>
[GET] /containers
Returns a list of containers on the server.

Example 10.15. Server Response

<response type="SUCCESS" msg="List of created containers">
  <kie-containers>
    <kie-container container-id="MyProjectContainer" status="STARTED">
      <release-id>
        <artifact-id>Project1</artifact-id>
        <group-id>com.redhat</group-id>
        <version>1.0</version>
      </release-id>
      <resolved-release-id>
        <artifact-id>Project1</artifact-id>
        <group-id>com.redhat</group-id>
        <version>1.0</version>
      </resolved-release-id>
    </kie-container>
  </kie-containers>
</response>
⁠[GET] /containers/{id}
Returns the status and information about the specified container.

Example 10.16. Server Response

⁠<response type="SUCCESS" msg="Info for container MyProjectContainer">
  <kie-container container-id="MyProjectContainer" status="STARTED">
    <release-id>
      <artifact-id>Project1</artifact-id>
      <group-id>com.redhat</group-id>
      <version>1.0</version>
    </release-id>
    <resolved-release-id>
      <artifact-id>Project1</artifact-id>
      <group-id>com.redhat</group-id>
      <version>1.0</version>
    </resolved-release-id>
  </kie-container>
</response>
[PUT] /containers/{id}
Allows you to create a new container in the execution server.

Example 10.17. Request to create a container

<kie-container container-id="MyRESTContainer">
  <release-id>
    <artifact-id>Project1</artifact-id>
    <group-id>com.redhat</group-id>
    <version>1.0</version>
  </release-id>
</kie-container>

Example 10.18. Example Server Response When Creating a Container

<response type="SUCCESS" msg="Container MyRESTContainer successfully deployed with module com.redhat:Project1:1.0">
  <kie-container container-id="MyProjectContainer" status="STARTED">
    <release-id>
      <artifact-id>Project1</artifact-id>
      <group-id>com.redhat</group-id>
      <version>1.0</version>
    </release-id>
    <resolved-release-id>
      <artifact-id>Project1</artifact-id>
      <group-id>com.redhat</group-id>
      <version>1.0</version>
    </resolved-release-id>
  </kie-container>
</response>
[DELETE] /containers/{id}
⁠Disposes a container specified by the id.

Example 10.19. Server Response disposing a container

<response type="SUCCESS" msg="Container MyProjectContainer successfully disposed."/>
[GET] /containers/{id}/release-id
Returns the full release id for the specified container.

Example 10.20. Server Response

⁠<response type="SUCCESS" msg="ReleaseId for container MyProjectContainer">
  <release-id>
    <artifact-id>Project1</artifact-id>
    <group-id>com.redhat</group-id>
    <version>1.0</version>
  </release-id>
</response>
The server will respond with a success or error message, such as:⁠

Example 10.21. Server Response

<response type="SUCCESS" msg="Release id successfully updated.">
  <release-id>
    <artifact-id>Project1</artifact-id>
    <group-id>com.redhat</group-id>
    <version>1.0</version>
  </release-id>
</response>
[GET] /containers/{id}/scanner
Returns information about the scanner for container's automatic updates.

Example 10.22. Server Response

<response type="SUCCESS" msg="Scanner info successfully retrieved">
  <kie-scanner status="DISPOSED"/>
</response>
[POST] /containers/{id}/scanner
Allows you to start or stop a scanner that controls polling for updated container deployments.

Example 10.23. Example Server Request to Start the Scanner

<kie-scanner status="STARTED" poll-interval="20"/>

Example 10.24. Server Response

<response type="SUCCESS" msg="Kie scanner successfully created.">
  <kie-scanner status="STARTED"/>
</response>
To stop the Scanner, replace the status with DISPOSED and remove the poll-interval attribute.