REST APIs

Problem API

Introduction

This APIs set is used to submit problems to BackSolver, to check computation status and to retrieve the solutions

All calls are prefixed by:

http://api.backsolver.com/1.0/[myaccount]/...
where:
  • [myaccount] is the account of your organization. You must replace it with your account url part you chose during signup.
  • 1.0 is the version of APIs. It must be 1.0

Warning

APIs must have a Content-Type: text/xml header because BackSolver returns an XML body response. It is a common mistake to forget it.

Submit a problem

To compute a problem it must be submitted to a queue.

First, the queue must be created and configured, through web console. All problems submitted to a queue rely on the SLAs associated with the queue. Currently the only configurable SLAs are daily and monthly budgets.

To submit a problem BackSolver expects a HTTP POST call to the url:

http://api.backsolver.com/1.0/[myaccount]/queues/[myqueue]

[myqueue] is the URL part of the queue you want to submit the problem to. If you have any doubt about the correct URL check the Queue Console to find it out.

Headers

Authentication

A basic-authentication header must be provided to identify the caller. The credentials are e-mail and password of an enabled user of your account. The user must be enabled and allowed to operate on the queue.

Note

Content-Type header MUST be text/xml

Model type

For each kind of model backSolver solves there are a couple of headers you must provide through HTTP headers

X-Model-Type identifies the problem (for example FCS identifies the “Finite capacity scheduling” problem). See the models section. X-Model-Version identities the spcific version of the model. (i.e. “1.0”)

Timeout

A X-Timeout header must be specified. It contains the computation timeout (in milliseconds).

Timeout is the the maximum allowed execution time. Problem will stop its execution in any case after the timeout has been reached. It is used to limit your budget consumption: big problems may find a solution fast but can refine it for long time.

If a timeout occurs the best solution found at that time will be available for download. If we find the optimum solution before the timeout we will stop budget consumption instantly.

Timeout is computed from the time the problem is dequed: queue time is not considered in timeout.

HTTP response values

201 Created

The problem has been created. During this step some formal validation has been applied too: if you obtain this status your problem has been formally validated.

A tipical response is like this:

HTTP/1.1 201 Created
Content-Length: nnn
Content-Type: text/xml;charset="utf-8"
Location: http://api.backsolver.com/1.0/myaccount/problems/1234

<?xml version="1.0"?>
<problem>
  <id>1234</id>
  <uri>http://api.backsolver.com/1.0/myaccount/problems/1234</uri>
</problem>

You can retrieve problem id (unique for the account) from the <id> tag Location header or <uri> tag are the location for all subsequent calls (status check, solution retrieve,...)

400 Badrequest

If the problem contains formal or semantic error (see model specifications) you will obtain a BadRequest response containing an XML report of errors found.

Here is an example:

HTTP/1.1 400 BadRequest
Content-Length: nnn
Content-Type: text/xml;charset="utf-8"

<?xml version="1.0"?>
<errors>
  <error>Too much tasks defined</error>
</errors>

If the request has malformed syntax you will obtain a 400 status error too.

403 Unauthorized

It occurs when:

  • username and/or password is incorrect
  • user is not allowed to submit problems to the target queue
  • target queue is disabled
404 Not found
The queue does not exists or account URL part is wrong

Check resolution status

After a problem has been submitted you can retrieve its computation status using the following HTTP GET call:

http://api.backsolver.com/1.0/[myaccount]/problems/[id]/status

Where:

  • [myaccount] is your account URL part
  • [id] is the problem id returned by problem submit call

Note

Content-Type header MUST be text/xml

HTTP responses values

200 Ok

Here is an example of a successful response:

HTTP/1.1 200 Ok
Content-Length: nnn
Content-Type: text/xml;charset="utf-8"

<?xml version="1.0"?>
<status>
  <code>SolvingWithSolution</code>
  <description>Solving with 7 solutions</description>
</status>
  • <description> tag contains a human readable description of the status

  • <code> tag contains the computation status. Possible values are:

    EnqueuedForSolving

    Problem is enqueued

    Solving

    BackSolver is solving the problem. No solutions found yet.

    SolvingWithSolution

    BackSolver is solving the problem. At least a solution has been found.

    SolvedWithSolution

    Problem solved. Best solution is available.

    Unsatisfiable

    Problem solved. No solution is available. This means BackSolver has proven your problem has no solution

    TimeoutWithSolution

    Computation stopped because timeout has been reached. The best solution found is available for download. You might obtain a better solution if you re-run the same problem for a longer time

    TimeoutWithoutSolution

    Computation stopped because timeout has been reached. No solution found but maybe there should be a solution if you re-run the same problem for a longer time

    TerminatedByClient

    Problem has been terminated by the client through a delete problem request

    TerminatedWithError

    BackSolver encountered an error during computation. No budget has been consumed

403 Unauthorized

It occurs when:

  • username and/or password is incorrect
  • user is not allowed to read the problem status
404 Not Found
Wrong problem id

Retrieve the solution

After a solution has been found you can retrieve it with the following HTTP GET call:

http://api.backsolver.com/1.0/[myaccount]/problems/[id]/solution

Where:

  • [myaccount] is your account URL part
  • [id] is the problem id returned by problem submit call

Note

Content-Type header MUST be text/xml

HTTP responses values

200 Ok

Here is an example of a successful response:

HTTP/1.1 200 Ok
Content-Length: nnn
Content-Type: text/xml;charset="utf-8"

<?xml version="1.0"?>
<solution>
  ...
</solution>

The body of the response contains the solution. It depends on the type of problem you submitted.

403 Unauthorized

It occurs when:

  • username and/or password is incorrect
  • user is not allowed to download the solution
404 Not Found

It occurs when:

  • Solution is not yet available
  • Problem ID is wrong