Synchronous and Asynchronous API Calls
Haven OnDemand APIs can run either synchronously or asynchronously.

Synchronous and Asynchronous API Calls

You can call Haven OnDemand APIs to run either synchronously or asynchronously.

In synchronous mode, Haven OnDemand processes the call immediately, and returns a single response, containing your results. You can use synchronous mode for small requests where you expect quick results. However, there are limitations to synchronous calls:

  • Synchronous requests automatically fail after two minutes if not completed.
  • You cannot check the status of a synchronous job.
  • If the connection is lost you must resubmit the request to get the results.

In asynchronous mode, Haven OnDemand receives the call, and returns a job ID, which allows you to track the status of the call. When the call is complete, the status message also returns the response and results. Haven OnDemand recommends using asynchronous mode for most purposes:

  • Some Haven OnDemand APIs, including audio-video analytics and some prediction APIs, are only available for asynchronous use.
  • You must use asynchronous mode to upload files larger than 10MB.
  • You can use asynchronous mode to submit multiple jobs in one request.
  • You can retrieve the result of an asynchronous request for up to two weeks after it was made.

Use Synchronous Mode

The /1/api/sync/<action>/<action-version> API call allows you to submit a synchronous job to Haven OnDemand. This request returns the job result immediately, typically in JSON or HTML.

For example, the following GET request sends a request for the Highlight API:

/1/api/sync/highlight/v1?text=text&highlight_expression=links&apikey=ABCDEFG

Use Asynchronous Mode

There are two forms of asynchronous API calls:

  • The /1/api/async/<action>/<action-version> API call allows you to submit a single asynchronous action request to Haven OnDemand.

  • The /1/job/ API call allows you to send an asynchronous job, which can include multiple actions that can each reference the same uploaded files.

For both asynchronous API forms, you can use the /1/job/status/<job-id> to get the status of the job, including results if the job is finished.

You can also use /1/job/result/<job-id>, which waits until the job has finished and then returns the result.

Submit a Single Asynchronous Action

To run an asynchronous request for a single action, use the /1/api/async/<action>/<action-version> API call. You specify the parameters for this call in the same way as for the synchronous requests. This API call is available for GET and POST.

Submit an Asynchronous Job

To submit an asynchronous job, use the /1/job API. This API is available only as a POST request. You can specify multiple actions in this type of request.

Example

<form
   action="http://<host>/1/job"
   method="post"
   enctype="multipart/form-data">
<input
   type="text"
   class="form-control"
   name="apikey"
   value= ABCDEFG >
<input
   type="text"
   name="job"
   value='{
   "actions": [
      { "name": "highlight", "version": "v1", "params": {
         "file": "file1",
         "highlight_expression": "breakPath"
      } }
   ]
}'>

   <input type="file" name="file1">
   <input type="submit" value="Submit">
</form>

Job format

The JSON format for asynchronous API requests is:

{
   "actions": [Action]
}

Action has the following format:

{
   "name": String,
   "version": String,
   "params": Params
}

Params is an object of key:value pairs, where the key is the parameter name string, and the value is the value to pass to that parameter. It has the following format:

{
   "paramName": "value",
   "paramName2": "value2"
}

Results from Asynchronous Requests

Both types of asynchronous API requests return the result in the following format:

{
   "jobID": String
}

The String is the UUID for the job, which you can use to track the status of the job.

Retrieve the Job Status

Use the /1/job/status/<job-id> API to retrieve the status of an asynchronous job, where <job-id> is the ID returned by the /1/job or /1/api/async/<action>/<action-version> call. This API is available only as a GET request.

You can also use /1/job/result/<job-id>, which waits until the job has finished and then returns the result.

Example

/1/job/status/0_f8202c34-9527-4d82-a27a-21de0e2f4834?apikey=ABCDEFG

Result

The following JSON is example output for the status API.

{
   "actions": [
      {
         "action": "Highlight",
         "status": "finished",
         "result": "<span class=\"highlight\">highlighted</span> text"
      },
      {
         "action": "Query",
         "status": "failed",
         "error": {
            "error": 4006,
            "reason": "Invalid job action parameter",
            "detail": "'maxresults' must be at least 1"
         }
      },
      {
         "action": "Detect Sentiment",
         "status": "queued"
      }
   ],
   "jobID": "0_f8202c34-9527-4d82-a27a-21de0e2f4834",
   "status": "queued"
}

The Status value shows the progress of the job, and can have one of the following values:

  • queued. The job is in the queue waiting to start.

  • in progress. The job is being processed by Haven OnDemand.

  • finished. The job has been completed.

  • failed. The job has failed permanently, and you must resend it.

The Result string only appears in the output when the job status is finished.

Error Responses

Error

In any request, when there is an error, Haven OnDemand returns details of the error in the following format:

{
	"error": Integer,
	"reason": String,
	"detail": *
}

The detail field is optional.