This is a simple API scenario with sample API calls and instructions on how to chain them together to complete a simple action using only APIs. Options that can be set via the APIs are extensive. Consult the respective sections of REST API documentation to find out more about all available options.
The Postman API platform was used to create the scenario.
In these examples, the standard request URL starts with https://cloud.memsource.com
. In case APIs are used by an organization in the US data center, the request URL should start with https://us.cloud.memsource.com
.
Scenario
-
Authentication
The user is authenticated (the API equivalent of logging in).
-
Creation
The creation of a simple project, jobs uploaded, and Linguist assignment with email notification.
-
Translation
Translation work performed outside of the API scenario (in any of the Editors).
-
API Function
Once the assignment is finished (marked as Completed by Linguist), the project's status is set to Completed and the finished document is downloaded from the project.
Methodology
Each individual REST API call has an appropriate method listed. Using an incorrect method (e.g. GET instead of POST in the project creation call) results in an unsuccessful API call.
Step 1: Authentication
There are two authentication methods:
-
Generates an authentication token valid for 24 hours. The token needs to be inserted into all following APIs. The token validates users and allows them to perform any other functions within the profile.
-
Allows the validation of an application. A validated application is in continuous communication with and needs no further authentication.
For the scenario, the Authentication API call is used. The generated token is required for all following API calls and is not listed in example parameters.
Use the Login API for authentication with required parameters. In this case, username and password are required.
-
Method
POST
-
Request URL
https://cloud.memsource.com/web/api2/v3/auth/login
-
Request body:
{ "userName":"username", "password":"password"}
-
Response
Authentication token.
Members of multiple TMS organizations have the same username and password for multiple accounts. In this case, the userUid
must be added to the request body to specify which organization the user wants to log in to. If not specified, the user is logged in to the default account associated with the given username and password.
Step 2: Project Creation, Import, and Assignment
Project Creation
Use the Projects API call to create a project with the mandatory parameters name, sourceLang, and targetLangs.
-
Method
POST
-
Request URL
https://cloud.memsource.com/web/api2/v3/projects
-
Request body
{ "name":"My project", "sourceLang":"en", "targetLangs":[ "de","fr" ]}
-
Response
Project UID (e.g. KmtNyVlz1skQd2aMVEipp7)
It is possible to create a project template using the Create project template
API call with the project UID from the last call.
-
Method
POST
-
Request URL
https://cloud.memsource.com/web/api2/v1/projectTemplates
-
Request body
{ "project": { "uid": "string" }, "name": "string", "importSettings": { "uid": "string" }, "useDynamicTitle": true, "dynamicTitle": "string" }
-
Response
Project Template UID (e.g. AmtNyVlz1skQd2aMVEipp8)
The most efficient way of creating projects is to use a project template. Use Create project from template with the Project Template UID from the last call to create a new project based on the settings of the project template.
The expression {templateUid}
serves as a placeholder in the request URL where the obtained Project Template UID is inserted.
-
Method
POST
-
Request URL
https://cloud.memsource.com/web/api2/v2/projects/applyTemplate/oNQiljwTGHpd2l1nnQRiu4
-
Request body
{ "name": "string", "sourceLang": "string", "targetLangs": [ "string" ], "workflowSteps": [ { "id": "string" } ], "dateDue": "2019-08-24T14:15:22Z", "note": "string", "client": { "id": "string" }, "businessUnit": { "id": "string" }, "domain": { "id": "string" }, "subDomain": { "id": "string" }, "costCenter": { "id": "string" } }{ "project": { "uid": "string" }, "name": "string", "importSettings": { "uid": "string" }, "useDynamicTitle": true, "dynamicTitle": "string" }
-
Response
Project UID (e.g. BmtNyVlz1skQd2aMVEipp9)
Job Creation
With the project UID from the last call, new jobs can be added directly into the newly created project using Create Job.
The expression {projectUid}
serves as a placeholder in the request URL where the obtained Project UID is inserted. With the Create Job API call, the Headers of the request must be changed to match the ones required by Phrase (in other calls, Postman automatically adds appropriate headers to the request).
All the import parameters need to be inserted into a custom Memsource header.
The Content-Disposition header must include the filename in a pre-defined format in order to correctly process the import request.
To import a source file, go to the body, select
and the option appears.-
Method
POST
-
Request URL
https://cloud.memsource.com/web/api2/v1/projects/KmtNyVlz1skQd2aMVEipp7/jobs
-
(Header) Content-Disposition
filename*=UTF-8''file.txt
-
(Header) Memsource
{"targetLangs":["de","fr"]}
-
(Header) Content-Type
application/octet-stream
-
Response
Job UID (e.g. dOYgeXzAdAbj4xFjuEVZP2)
AsyncRequest UID
Use Get asynchronous request with the AsyncRequest UID from the Create Job call to check that the job was successfully created and that it is functional.
The returned Job UID is unique in each workflow step of the project. Therefore, if the job is created in a project with workflow, the response returns a unique Job UID for each workflow step.
Re-usable import settings can be configured with the Create import settings call. An import setting UID that can be used in the create job call is received in the response.
To assign providers to the job (unless assigned directly in the Create job call) use the Edit job call.
The ID of the Provider that is inserted in the call can be obtained in two ways:
-
To retrieve the ID from the Phrase application, follow these steps:
-
Use the List users API call.
This API call does not require any specific parameters, and it will return a list of all users in the account. The response contains both usernames and IDs.
An optional parameter, userName, can be added to the query allowing you to list only users with specific usernames.
Notify Assigned Users
The job UID can then be used as an optional parameter in Notify assigned users call along with the emailTemplate parameter representing the ID of the email template to be used. This can be obtained by using List email templates call.
-
Request URL
https://cloud.memsource.com/web/api2/v1/projects/KmtNyVlz1skQd2aMVEipp7/jobs/notifyAssigned
-
Response
Empty (Status 204: No content)
This is where the translator would start to work in their profile just as if the Phrase UI was being used. After the job is finished, the PM in charge receives a notification, and the next part of the scenario is initiated. A callback can be intercepted via webhooks to automatically start the next part of the scenario but this will not be addressed in this example.
Step 3: Download Translated (Complete) File, Set Project to Completed
Download translated file
This scenario works with the assumption that a translator finishes their assignment (marks the job as Completed), but the completed file can be downloaded at any time, the job does not need to have the Completed status.
To download a translated file, two API calls are needed: Download target file (async) and Download target file based on async request calls.
The first step is to call Download target file (async) with the projectUid and jobUid parameters. If you are downloading the completed file from a project with multiple workflow steps, make sure you use the jobUid from the specific workflow step from which you would like to download the completed file, e.g. revision workflow step.
-
To retrieve the jobUID for a specific workflow step from the Phrase application, follow these steps:
-
Open the project.
-
In the Jobs table, switch to the workflow step from which you would like to download the completed file.
-
Copy the unique part of the URL after /job from the browser.
-
-
Use the List jobs API call.
This endpoint returns a list of jobs within the specified project. Use the call with the
workflowLevel
query parameter. This parameter is a non-zero based parameter that indicates the workflow step the returned jobs belong to. If left unspecified, its value is set to1
(= first workflow step) by default. For example, if you need to get the jobs from the revision step, specify that step's number in the query parameter, i.e2
.
The Download target file (async) call initiates an asynchronous request to generate and download the target file containing translations. It does not directly provide the target file within the response but an asyncRequestId required for the following call.
-
Method
PUT
-
Request URL
https://cloud.memsource.com/web/api2/v2/projects/KmtNyVlz1skQd2aMVEipp7/jobs/dOYgeXzAdAbj4xFjuEVZP2/targetFile
-
Response
AsyncRequest ID
Use Get asynchronous request with the asyncRequestID from the response to check that the request is completed. Once the asynchronous request is completed, you can download the target file using the Download target file based on async request call. The asyncRequestId can be used only once. Once the download is initiated, the asyncRequestId becomes invalid for further use.
-
Method
GET
-
Request URL
https://cloud.memsource.com/web/api2/v2/projects/KmtNyVlz1skQd2aMVEipp7/jobs/dOYgeXzAdAbj4xFjuEVZP2/downloadTargetFile/1291716982
-
Response
Binary response with the completed file itself
Set Project to Completed
To finalize the project once the job in the project is complete, use the Edit project status call with the mandatory parameters projectUid and status to change the status of the entire project to Completed. This change is a manual one, but if Project Status Automation is used, the status will be changed automatically. It is also possible to wait for a webhook and initiate other actions based on the callback received.
-
Method
POST
-
Request URL
https://cloud.memsource.com/web/api2/v1/projects/KmtNyVlz1skQd2aMVEipp7/setStatus
-
Request body
{ "status": "COMPLETED"}
-
Response
Empty (Status 204: No content)