docs/shared-kie-docs/src/main/asciidoc/KieServer/RestAPI-section.adoc

[[_kie.ksrestapi]]
= Kie Server REST API


The Execution Server supports the following commands via the REST API. 

Please note the following before using these commands: 



* The base URL for these will remain as the endpoint defined earlier (for example: `http://SERVER:PORT/CONTEXT/services/rest/server/` )
* All requests require basic HTTP Authentication for the role kie-server as indicated earlier.


== [GET] /


Returns the Execution Server information

.Example Server Response
====
[source,xml]
----
<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.
E.g: create-container, list-containers, dispose-container and call-container.



* CreateContainerCommand
* GetServerInfoCommand
* ListContainersCommand
* CallContainerCommand
* DisposeContainerCommand
* GetContainerInfoCommand
* GetScannerInfoCommand
* UpdateScannerCommand
* UpdateReleaseIdCommand

The commands itself can be found in the `org.kie.server.api.commands` package. 

== [GET] /containers

Returns a list of containers that have been created on this Execution Server.

.Example Server Response
====
[source,xml]
----
<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>
----
====

The endpoint supports also filtering based on `ReleaseId` and `container status`. Examples:

* `/containers?groupId=org.example` - returns only containers with the specified groupId
* `/containers?groupId=org.example&artifactId=project1&version=1.0.0.Final` - returns only containers with the specified `ReleaseId`
* `/containers?status=started,failed` - returns containers which are either started or failed


== ⁠[GET] /containers/{id}


Returns the status and information about a particular container.
For example, executing `http://SERVER:PORT/CONTEXT/services/rest/server/containers/MyProjectContainer` could return the following example container info.

.Example Server Response
====
[source,xml]
----
⁠<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.
For example, to create a Container with the id of *MyRESTContainer* the complete endpoint will be: ``http://SERVER:PORT/CONTEXT/services/rest/server/containers/MyRESTContainer``.
An example of request is:⁠

.Example Request to create a container
====
[source,xml]
----
<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>
----
====


And the response from the server, if successful, would be be:

.Example Server Response when creating a container
====
[source,xml]
----
<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 the Container specified by the id.
For example, executing `http://SERVER:PORT/CONTEXT/services/rest/server/containers/MyProjectContainer` using the DELETE HTTP method will return the following server response:⁠

.Example Server Response disposing a container
====
[source,xml]
----
<response type="SUCCESS" msg="Container MyProjectContainer successfully disposed."/>
----
====

== [POST] /containers/instances/{id}


Executes operations and commands against the specified Container.
You can send commands to this Container in the body of the POST request.
For example, to fire all rules for Container with id MyRESTContainer (``http://SERVER:PORT/CONTEXT/services/rest/server/containers/instances/MyRESTContainer``), you would send the fire-all-rules command to it as shown below (in the body of the POST request):

.Example Server Request to fire all rules
====
[source,xml]
----
<fire-all-rules/>
----
====


Following is the list of supported commands: 

* AgendaGroupSetFocusCommand
* ClearActivationGroupCommand
* ClearAgendaCommand
* ClearAgendaGroupCommand
* ClearRuleFlowGroupCommand
* DeleteCommand
* InsertObjectCommand
* ModifyCommand
* GetObjectCommand
* InsertElementsCommand
* FireAllRulesCommand
* QueryCommand
* SetGlobalCommand
* GetGlobalCommand
* GetObjectsCommand
* BatchExecutionCommand

These commands can be found in the `org.drools.core.command.runtime` package. 

== [GET] /containers/{id}/release-id


Returns the full release id for the Container specified by the id.

.Example Server Response
====
[source,xml]
----
⁠<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>
----
====

== [POST] /containers/{id}/release-id


Allows you to update the release id of the container deployment.
Send the new complete release id to the Server.

.Example Server Request
====
[source,xml]
----
<release-id>
  <artifact-id>Project1</artifact-id>
  <group-id>com.redhat</group-id>    
  <version>1.1</version>
</release-id>
----
====


The Server will respond with a success or error message, similar to the one below:⁠

.Example Server Response
====
[source]
----
<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 this Container's automatic updates.⁠

.Example Server Response
====
[source,xml]
----
<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.
To start the scanner, send a request similar to: `http://SERVER:PORT/CONTEXT/services/rest/server/containers/{container-id}/scanner` with the following POST data.⁠

.Example Server Request to start the scanner
====
[source,xml]
----
<kie-scanner status="STARTED" poll-interval="2000"/>
----
====


⁠The poll-interval attribute is in milliseconds.
The response from the server will be similar to:⁠

.Example Server Response
====
[source,xml]
----
<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.