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 our REST API documentation to find out more about all available options.
In these examples, the standard request URL starts with https://cloud.memsource.com
. In case APIs are used by an organization in the US Datacenter, 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 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:
-
Authentication API call:
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/v1/auth/login
-
Request body:
{ "userName":"username", "password":"password"}
-
Response
Authentication token.
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/v1/projects
-
Request body
{ "name":"My project", "sourceLang":"en", "targetLangs":[ "de","fr" ]}
-
Response
Project UID (e.g. KmtNyVlz1skQd2aMVEipp7)
Job Creation
With the 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 Phrase 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) Phrase
{"targetLangs":["de","fr"]}
-
(Header) Content-Type
application/octet-stream
-
Response
Job UID (e.g. dOYgeXzAdAbj4xFjuEVZP2)
-
AsyncRequest UID
Use /api2/v1/async/{asyncRequestId} to check that the job was successfully created and that it is functional.
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 /api2/v1/projects/{projectUid}/jobs/{jobUid} endpoint.
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 /api2/v1/projects/{projectUid}/jobs/notifyAssigned along with the emailTemplate parameter representing the ID of the email template to be used. This can be obtained from the Phrase UI or by using /api2/v1/emailTemplates.
-
Request URL
https://cloud.memsource.com/web/api2/v1/projects/KmtNyVlz1skQd2aMVEipp7/jobs/notifyAssigned
-
Response
Empty
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 File, Set Project to Completed
The API call /api2/v1/projects/{projectUid}/jobs/{jobUid}/targetFile with the parameter jobUid can be used to retrieve the translated content.
-
Method
GET
-
Request URL
https://cloud.memsource.com/web/api2/v1/projects/KmtNyVlz1skQd2aMVEipp7/jobs/dOYgeXzAdAbj4xFjuEVZP2/targetFile
-
Response
Binary response with the completed file itself
Once the job in the project is completed, use the /api2/v1/projects/{projectUid}/setStatus with the mandatory parameters project 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