A set of API calls is available which allow for:
-
Integration of Phrase and any third party software (translation management tools, CMSs, etc.)
-
Development of a translator's workbench. The CAT editor is built on top of public APIs.
-
Creation of a brand new tool or service using Phrase in its backend.
Basic Workflow
Procedures and workflow must be understood before using APIs. It is recommended to be familiar with a procedure in Phrase before implementing the related API.
The basic workflow is:
-
Create a TM, TB and optionally, add a machine translation engine.
-
Create a project with the TM/TB/machine translation engine attached (if needed).
-
Save the project as a project template and reuse it to create a new translation project.
-
Upload your file for translation to the project (creat a job).
-
You can then analyze, pre-translate or assign the job to a Linguist.
Asynchronous APIs
Asynchronous APIs should always be preferred to their synchronous counterparts. If calling synchronous APIs, there is a chance of receiving timeout expired responses when processing large batches of files or even a single large file. Synchronous APIs should only be used for small files and small scale integration.
Polling
After calling an asynchronous API, an instant response is received including the identifier request. Use this identifier to check the status of the request by calling getAsyncRequest and checking the asyncResponse field. This polling approach can lead to a number of getAsyncRequest calls before receiving an asyncResponse that is not null.
Callbacks
As a response to the drawbacks of the polling approach to asynchronous requests, support for callbacks in all asynchronous APIs is supported. When calling an asynchronous request, specify a URL (in the callbackUrl parameter) that is requested after the work initiated by the asynchronous request is complete.
Callbacks are requested via HTTP POST calls and the data is passed on in the body encoded as JSON. The JSON object always contains:
-
Information about the asynchronous request (the same as when calling getAsyncRequest).
-
Detailed information about the result of the action such as a full analysis or job details.
{ "asyncRequest": { ... } "analyse": { ... } }
If a callback URL is not accessible, the request is repeated after 2, 4, 8, 16, and 30 minutes until 10 retries have failed.
Callback URL must respond with the 200 OK HTTP status code to be considered successful.