Asynchronous operations

Operations that take more time to execute are most often executed "asynchronously" i.e. in the background. With such operations your API call either immediately returns the final result (if the operation was very quick) or it returns the ID of the operation if executing in the background. The status can then be polled in regular intervals.

Submitting an asynchronous API call

Every asynchronous API method returns the same JSON. Here the trm node tells whether the call immediately finished or failed, or whether it was started in the background and will take some time to complete. In the latter case you would poll the system for the completion of the operation (to get the results). The JSON is:

{
    "trm": {
        "requestid": 559,
        "isbatch": false,
        "status": "Waiting",
        "statusText": "Waiting..."
    }
}

Working with asynchronous operations

The steps are:

1. Submit your API method. 
2. If the API call returns status "Finished" or "Failed" then you are done. Otherwise, the operation now runs in the background, go to step 3.
   
   
3. Wait between 2 to 5 seconds
4. Call API method /api/trm/status with the value contained in trm.requestid
5. This method returns the same JSON object as above. If status is "Finished" or "Failed" then you are done!
6. If the status is "Waiting" or "Executing" go back to step 3.

When polling an operation status please always sleep 2 to 5 seconds in between calls. Our systems may throttle all your API activity if overused. Consider using callbacks, see below.

Using callbacks to avoid polling

Why poll when you can have Wordbee notify your servers with callback URLs?

See Callbacks (with asynchronous operations) for more details.

Why do asynchronous operations sometimes return results immediately and sometimes not?

In some cases, the operation result can be obtained immediately. There are 2 cases:

• The API method was called with bad parameters. In that case you immediately receive a result with "Failed" status.
• The API method executes instantly because the parameters allow to do so. In that case you immediately receive a result with "Success" status.

The good thing is that the JSON returned by the API method and the poll call are identical. 

Can I start multiple asynchronous operations simultaneously?

Yes.

There is no limitation.

Can I view a log with all asynchronous operations?

Yes. Log in to Wordbee Translator as administrator. Then click "Settings" > "Activity" > "User operations":

Why do you suggest to sleep a few seconds in between poll calls?

To keep the API call frequency to a reasonable amount.

Imagine you'd launch 100 asynchronous operations and you poll all of them without sleeping. This may rapidly lead to hundreds of API calls per second.

How fast are my operations processed?

When an operation is delegated to the background, it is first inserted into a queue. Application servers are then picking up items in the order they are inserted.

Each Wordbee Translator platform is assigned a maximum number of "slots" for background operations. This is the number of operations that are executed simultaneously. This means that if you submit 100 operations, they will not all start immediately.

Examples

The result if the operation did not complete immediately but runs in the background. Use the requestid to poll the operation status in regular intervals using trm/status

{
	"trm": {
		"requestid": 559,
		"isbatch": false,
		"status": "Waiting",
		"statusText": "Waiting..."
	}
}

Oups, this operation failed:

{
	"trm": {
		"requestid": 559,
		"isbatch": false,
		"status": "Failed",
		"statusText": "Operation failed!",
		"statusInfo": "The parameter xy was not properly supplied"
	}
}

The operation terminated with success. Results are included in the custom and/or results nodes.

Note that this is a sample result from resources/segments/view/export. It is used to export a job or project to XLIFF. The XLIFF file itself is downloaded with the "fileref" token - please see the documentation for more details.

{
	"trm": {
		"requestid": 0,
		"isbatch": false,
		"status": "Finished",
		"statusText": "Finished!"
	},
	"custom": {
		"fileref": "ea9c1adeb02f4a9ebe8771583c12fa6b",
		"filename": "export_wm-1180_en_fr.xlf",
		"segments": 10
	}
}