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

= OptaPlanner REST API


The Kie Server supports the following Planner REST APIs.
As usual, all these APIs are also available through JMS and the Java client API.
Please also note:



* 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.
* To get a specific marshalling format, add the HTTP headers `Content-Type` and optional `X-KIE-ContentType` in the HTTP request. For example:
+

[source]
----
Content-Type: application/xml
X-KIE-ContentType: xstream
----

[NOTE]
====
`X-KIE-ContentType` supports the following values: `xstream`, `xml`, `json`.
====

The example requests and responses used below presume that a Kie Container is built using the optacloud example of Planner Workbench, by calling a `PUT` on `/services/rest/server/containers/optacloud-kiecontainer-1` with this content:

[source,xml]
----
<kie-container container-id="optacloud-kiecontainer-1">
  <release-id>
    <group-id>opta</group-id>
    <artifact-id>optacloud</artifact-id>
    <version>1.0.0</version>
  </release-id>
</kie-container>
----

== [GET] /containers


Returns the list of created containers.

.Example Server Response (XStream)
====
[source,xml]
----
<response type="SUCCESS" msg="List of created containers">
  <result class="kie-containers">
    <kie-container>
      <container-id>optacloud-kiecontainer-1</container-id>
        <release-id>
          <group-id>optacloud</group-id>
          <artifact-id>optacloud</artifact-id>
          <version>1.0.0</version>
        </release-id>
        <resolved-release-id>
          <group-id>optacloud</group-id>
          <artifact-id>optacloud</artifact-id>
          <version>1.0.0</version>
        </resolved-release-id>
        <status>STARTED</status>
        <scanner>
          <status>DISPOSED</status>
        </scanner>
    </kie-container>
  </result>
</response>
----
====


== [PUT] /containers/{containerId}/solvers/{solverId}


Creates a new solver with the given `{solverId}` in the container ``{containerId}``.
The request's body is a marshalled SolverInstance entity that must specify the solver configuration file.

The following is an example of the request and the corresponding response.

.Example Server Request (XStream)
====
[source,xml]
----
<solver-instance>
  <solver-config-file>optacloud/optacloud/cloudSolverConfig.solver.xml</solver-config-file>
</solver-instance>
----
====

.Example Server Response (XStream)
====
[source,xml]
----
<solver-instance>
  <container-id>optacloud-kiecontainer-1</container-id>
  <solver-id>solver1</solver-id>
  <solver-config-file>optacloud/optacloud/cloudSolverConfig.solver.xml</solver-config-file>
  <status>NOT_SOLVING</status>
  <score />
</solver-instance>
----
====


== [GET] /containers/{containerId}/solvers


Returns the list of solvers created in the container.

.Example Server Response (XStream)
====
[source,xml]
----
<org.kie.server.api.model.instance.SolverInstanceList>
  <solvers>
    <solver-instance>
      <container-id>optacloud-kiecontainer-1</container-id>
      <solver-id>solver2</solver-id>
      <solver-config-file>optacloud/optacloud/cloudSolverConfig2.solver.xml</solver-config-file>
      <status>NOT_SOLVING</status>
      <score />
    </solver-instance>
    <solver-instance>
      <container-id>optacloud-kiecontainer-1</container-id>
      <solver-id>solver1</solver-id>
      <solver-config-file>optacloud/optacloud/cloudSolverConfig.solver.xml</solver-config-file>
      <status>NOT_SOLVING</status>
      <score />
    </solver-instance>
  </solvers>
</org.kie.server.api.model.instance.SolverInstanceList>
----
====


== [GET] /containers/{containerId}/solvers/{solverId}


Returns the current state of the solver `{solverId}` in container ``{containerId}``.

.Example Server Response (XStream)
====
[source,xml]
----
<solver-instance>
  <container-id>optacloud-kiecontainer-1</container-id>
  <solver-id>solver1</solver-id>
  <solver-config-file>optacloud/optacloud/cloudSolverConfig.solver.xml</solver-config-file>
  <status>NOT_SOLVING</status>
  <score />
</solver-instance>
----
====


== [POST] /containers/{containerId}/solvers/{solverId}/state/solving


Starts the solver {solverId} in container {containerId} if it is not executing yet.
The request's body is a marshalled `PlanningSolution` to be optimized.

The following is an example to solve the OptaCloud problem with 2 computers and 6 processes.
The solver runs asynchronously. Send a request to the bestsolution URL to get the best solution.

.Example Server Request (XStream)
====
[source,xml]
----
<optacloud.optacloud.CloudSolution id="1">
  <computerList id="2">
    <optacloud.optacloud.Computer id="3">
      <cpuPower>24</cpuPower>
      <memory>96</memory>
      <networkBandwidth>16</networkBandwidth>
      <cost>4800</cost>
    </optacloud.optacloud.Computer>
    <optacloud.optacloud.Computer id="4">
      <cpuPower>6</cpuPower>
      <memory>4</memory>
      <networkBandwidth>6</networkBandwidth>
      <cost>660</cost>
    </optacloud.optacloud.Computer>
  </computerList>
  <processList id="5">
    <optacloud.optacloud.Process id="6">
      <requiredCpuPower>1</requiredCpuPower>
      <requiredMemory>1</requiredMemory>
      <requiredNetworkBandwidth>1</requiredNetworkBandwidth>
    </optacloud.optacloud.Process>
    <optacloud.optacloud.Process id="7">
      <requiredCpuPower>3</requiredCpuPower>
      <requiredMemory>6</requiredMemory>
      <requiredNetworkBandwidth>1</requiredNetworkBandwidth>
    </optacloud.optacloud.Process>
    <optacloud.optacloud.Process id="8">
      <requiredCpuPower>1</requiredCpuPower>
      <requiredMemory>1</requiredMemory>
      <requiredNetworkBandwidth>3</requiredNetworkBandwidth>
    </optacloud.optacloud.Process>
    <optacloud.optacloud.Process id="9">
      <requiredCpuPower>1</requiredCpuPower>
      <requiredMemory>2</requiredMemory>
      <requiredNetworkBandwidth>11</requiredNetworkBandwidth>
    </optacloud.optacloud.Process>
    <optacloud.optacloud.Process id="10">
      <requiredCpuPower>1</requiredCpuPower>
      <requiredMemory>1</requiredMemory>
      <requiredNetworkBandwidth>1</requiredNetworkBandwidth>
    </optacloud.optacloud.Process>
    <optacloud.optacloud.Process id="11">
      <requiredCpuPower>1</requiredCpuPower>
      <requiredMemory>1</requiredMemory>
      <requiredNetworkBandwidth>5</requiredNetworkBandwidth>
    </optacloud.optacloud.Process>
  </processList>
</optacloud.optacloud.CloudSolution>
----
====

.Example Server Request (JAXB)
====
[source,xml]
----
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<cloudSolution>
  <computerList>
    <cost>4800</cost>
    <cpuPower>24</cpuPower>
    <memory>96</memory>
    <networkBandwidth>16</networkBandwidth>
  </computerList>
  <computerList>
    <cost>660</cost>
    <cpuPower>6</cpuPower>
    <memory>4</memory>
    <networkBandwidth>6</networkBandwidth>
  </computerList>
  <processList>
    <requiredCpuPower>1</requiredCpuPower>
    <requiredMemory>1</requiredMemory>
    <requiredNetworkBandwidth>1</requiredNetworkBandwidth>
  </processList>
  <processList>
    <requiredCpuPower>3</requiredCpuPower>
    <requiredMemory>6</requiredMemory>
    <requiredNetworkBandwidth>1</requiredNetworkBandwidth>
  </processList>
  <processList>
    <requiredCpuPower>1</requiredCpuPower>
    <requiredMemory>1</requiredMemory>
    <requiredNetworkBandwidth>3</requiredNetworkBandwidth>
  </processList>
  <processList>
    <requiredCpuPower>1</requiredCpuPower>
    <requiredMemory>2</requiredMemory>
    <requiredNetworkBandwidth>11</requiredNetworkBandwidth>
  </processList>
  <processList>
    <requiredCpuPower>1</requiredCpuPower>
    <requiredMemory>1</requiredMemory>
    <requiredNetworkBandwidth>1</requiredNetworkBandwidth>
  </processList>
  <processList>
    <requiredCpuPower>1</requiredCpuPower>
    <requiredMemory>1</requiredMemory>
    <requiredNetworkBandwidth>5</requiredNetworkBandwidth>
  </processList>
</cloudSolution>
----
====


.Example Server Request (JSON)
====
[source,json]
----
{
  "optacloud.optacloud.CloudSolution": {
    "computerList": [
      {
        "cpuPower": 24,
        "memory": 96,
        "networkBandwidth": 16,
        "cost": 4800
      },
      {
        "cpuPower": 6,
        "memory": 4,
        "networkBandwidth": 6,
        "cost": 660
      }
    ],
    "processList": [
      {
        "requiredCpuPower": 1,
        "requiredMemory": 1,
        "requiredNetworkBandwidth": 1
      },
      {
        "requiredCpuPower": 3,
        "requiredMemory": 6,
        "requiredNetworkBandwidth": 1
      },
      {
        "requiredCpuPower": 1,
        "requiredMemory": 1,
        "requiredNetworkBandwidth": 3
      },
      {
        "requiredCpuPower": 1,
        "requiredMemory": 2,
        "requiredNetworkBandwidth": 11
      },
      {
        "requiredCpuPower": 1,
        "requiredMemory": 1,
        "requiredNetworkBandwidth": 1
      },
      {
        "requiredCpuPower": 1,
        "requiredMemory": 1,
        "requiredNetworkBandwidth": 5
      }
    ]
  }
}
----
====


== [POST] /containers/{containerId}/solvers/{solverId}/state/terminating-early

Requests the solver to terminate early, if it is running.
This doesn't delete the solver, the best solution can still be retrieved.

== [GET] /containers/{containerId}/solvers/{solverId}/bestsolution


Returns the best solution found at the time the request is made.
If the solver hasn't terminated yet (so the `status` field is still ``SOLVING``), it will return the best solution found up to then, but later calls can return a better solution.⁠

.Example Server Response (XStream)
====
[source,xml]
----
<solver-instance>
  <container-id>optacloud-kiecontainer-1</container-id>
  <solver-id>solver1</solver-id>
  <solver-config-file>optacloud/optacloud/cloudSolverConfig.solver.xml</solver-config-file>
  <status>NOT_SOLVING</status>
  <score scoreClass="org.optaplanner.core.api.score.buildin.hardsoft.HardSoftScore">0hard/-5460soft</score>
  <best-solution class="optacloud.optacloud.CloudSolution">
    <computerList>
      <optacloud.optacloud.Computer>
        <cpuPower>24</cpuPower>
        <memory>96</memory>
        <networkBandwidth>16</networkBandwidth>
        <cost>4800</cost>
      </optacloud.optacloud.Computer>
      <optacloud.optacloud.Computer>
        <cpuPower>6</cpuPower>
        <memory>4</memory>
        <networkBandwidth>6</networkBandwidth>
        <cost>660</cost>
      </optacloud.optacloud.Computer>
    </computerList>
    <processList>
      <optacloud.optacloud.Process>
        <requiredCpuPower>1</requiredCpuPower>
        <requiredMemory>1</requiredMemory>
        <requiredNetworkBandwidth>1</requiredNetworkBandwidth>
        <computer reference="../../../computerList/optacloud.optacloud.Computer[2]"/>
      </optacloud.optacloud.Process>
      <optacloud.optacloud.Process>
        <requiredCpuPower>3</requiredCpuPower>
        <requiredMemory>6</requiredMemory>
        <requiredNetworkBandwidth>1</requiredNetworkBandwidth>
        <computer reference="../../../computerList/optacloud.optacloud.Computer"/>
      </optacloud.optacloud.Process>
      <optacloud.optacloud.Process>
        <requiredCpuPower>1</requiredCpuPower>
        <requiredMemory>1</requiredMemory>
        <requiredNetworkBandwidth>3</requiredNetworkBandwidth>
        <computer reference="../../../computerList/optacloud.optacloud.Computer"/>
      </optacloud.optacloud.Process>
      <optacloud.optacloud.Process>
        <requiredCpuPower>1</requiredCpuPower>
        <requiredMemory>2</requiredMemory>
        <requiredNetworkBandwidth>11</requiredNetworkBandwidth>
        <computer reference="../../../computerList/optacloud.optacloud.Computer"/>
      </optacloud.optacloud.Process>
      <optacloud.optacloud.Process>
        <requiredCpuPower>1</requiredCpuPower>
        <requiredMemory>1</requiredMemory>
        <requiredNetworkBandwidth>1</requiredNetworkBandwidth>
        <computer reference="../../../computerList/optacloud.optacloud.Computer"/>
      </optacloud.optacloud.Process>
      <optacloud.optacloud.Process>
        <requiredCpuPower>1</requiredCpuPower>
        <requiredMemory>1</requiredMemory>
        <requiredNetworkBandwidth>5</requiredNetworkBandwidth>
        <computer reference="../../../computerList/optacloud.optacloud.Computer[2]"/>
      </optacloud.optacloud.Process>
    </processList>
    <score>0hard/-5460soft</score>
  </best-solution>
</solver-instance>
----
====

== [DELETE] /containers/{containerId}/solvers/{solverId}


⁠Disposes the solver `{solverId}` in container ``{containerId}``.
If it hasn't terminated yet, it terminates it first.