Model submission

Armed with your API Key, a language you’re comfortable in, and a model you’d like to submit, we can complete a round trip against the API.

Solving models can sometimes take a hot minute. For this reason, when you POST a model to the API, we don’t block and hold the request. Instead, we return a GUID (Globally Unique Identifier) which will allow you to retrieve the results of the solve when they’re complete. The GUIDs that the API returns on a successful POST take on the following form: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx and look something like this 4c843bc9-2c92-4de1-8f4b-bc7fe8d1289f.

A natural question to ask is how would you know when the results are complete. The truth is we often don’t know exactly how long a problem will take to solve, so when a request is made for results that aren’t complete we hold the request open on our side for 30 seconds in case the results do complete in that interval. If we hit the 30 second time limit and there are still no new results available, we return the last result that was available.

So how could you use this design pattern to your advantage? Say you have a couple of small problems you want to run, you can simply POST all the models you want solved, we’ll queue them up on our side, and you can retrieve the results using the GUIDs for each model. This means that you don’t have to wait for one to finish before running the next model. This is great for production environments where you may have a territory split up and want to run a bunch of schedules in parallel.

For smaller problems, you don’t really see this benefit as when you run the GET request to retrieve the solution to the model, the results are simply returned as the solve has completed in a few milliseconds. You still get the full log of solver messages (which may include useful pieces of infromation on what happened during the solve), along with a populated solution response.

To summarise:

1. Submit a model to the API (POST): the API adds the model to the queue, and immediately returns a GUID (requestID)
2. The requestID can then be used in a GET request to retrieve the solution response.
3. If the response is unchanged since your last GET request, we hold the request open for 30 seconds, or until an update is provided by the solver (whichever comes first).
4. You can then submit an additional GET request to get the model solution (if the solve is still busy), or process the response payload (which is model dependent).

If you’re looking for examples of best-practice for setting up a robust model-retrieval loop, check out the examples on github in the language that closest suits your needs.