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. |
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:
| object | |
trm.status | The status 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? |
The steps are:
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. |
Why poll when you can have Wordbee notify your servers with callback URLs?
See Callbacks (with asynchronous operations) for more details.
In some cases, the operation result can be obtained immediately. There are 2 cases:
The good thing is that the JSON returned by the API method and the poll call are identical.
Yes.
There is no limitation.
Yes. Log in to Wordbee Translator as administrator. Then click "Settings" > "Activity" > "User operations":
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.
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.
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 } } |