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:

Property	Description	Type
	Status of operation
trm	A JSON object with the status of the operation. Example: { "trm": { "requestid": 559, "isbatch": false, "status": "Waiting", "statusText": "Waiting..." } }	object
trm.status	The status of the operation: Finished: The operation terminated with success. Failed: The operation terminated with an error. Error information is stored in "trm.statusInfo" Waiting or Executing: The operation is running in the background. Use the /api/trm/status API method to poll for the completion of the operation.	string
trm.requestid	A unique ID assigned to this operation. You can poll the system with this ID. If the operation finished or failed then the value is 0.	int
trm.statusText	Additional operation work progress information.	string
trm.statusInfo	Added in case of error. Contains error of a failed operation.	string?
trm.isbatch	Internal use only.	bool
	Results - populated when operation is finished.
result	Only populated if status is "Finished". Content depends on the API call - check out documentation. Example:	object?
custom	Only populated if status is "Finished". Content depends on the API call - check out documentation.	object?

Working with asynchronous operations

The steps are:

Submit your API method.
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.
Wait between 2 to 5 seconds
Call API method /api/trm/status with the value contained in trm.requestid
This method returns the same JSON object as above. If status is "Finished" or "Failed" then you are done!
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
	}
}

Browser not supported