9.7. The REST API for Intelligent Process Server Administration

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

9.7.1. Managed Intelligent Process Server Environment

When you have a managed Intelligent Process Server setup, you need to manage Intelligent Process 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 Intelligent Process Server instances.

Example 9.10. 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 Intelligent Process Server instance.

Example 9.11. 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 Intelligent Process Server instance with the specified id.

Example 9.12. Example Request to Create a New Intelligent Process 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 Intelligent Process Server instance with the specified id.
[GET] /admin/server/{id}/containers/{containerId}
Returns the container information including its release id.

Example 9.13. 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 9.14. 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.

9.7.2. Unmanaged Intelligent Process 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 9.15. 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 9.16. 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 9.17. 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 9.18. 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 9.19. 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 9.20. 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 9.21. 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 9.22. 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 9.23. 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 9.24. 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 9.25. Example Server Request to Start the Scanner

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

Example 9.26. 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.