The article below will provide a simple API scenario with sample API calls and how to chain them together to complete a simple action using only Memsource APIs.
Each section includes a link to the precise API call where additional information can be found, as well as a sample API call to illustrate a simple scenario. However, the options that can be set via the APIs are quite extensive. Please consult the respective sections of our API documentation to find more about all the possible options available.
All sample responses include only the information relevant for this scenario. For the complete Responses and the range of information they can contain, please refer to our documentation.
To test this scenario, you can use the Google Chrome extension called Postman (or a separate application).
The scenario discussed in this article will cover the following process:
The user will authenticate himself to be able to perform the following action (the API equivalent of logging in). The next step will be the creation of a simple project, uploading of jobs, and assignment of a Linguist, including sending an email notification. The actual translation work will be performed outside of the API scenario (in any of the Editors). Once the assignment is finished (marked as Completed by Linguist), the scenario will continue by changing the project's status to Completed and downloading of the finished document from the project.
Both GET and POST methods are supported in Memsource calls; you can choose what is more suitable for you—see the general Memsource API User manual for more information.
You can use either of the following and send the parameters in the body.
Note: The Post method can combine parameters in the URL and the body. For example, the token can be part of the URL and other parameters can be sent in the body.
Please be aware that, for example, "create job" needs the POST method to send the file in the body (This is not available with the GET method).
How to Use Postman to Test APIs
The screenshot below demonstrates how to orient yourself in the Postman environment and how to use it to test the API scenario described in this article.
Step 1: Authentication
There are 2 possible ways to authenticate:
- Authentication API call: this call generates an authentication token that is valid for 24 hours. The token then needs to be inserted into all the following APIs. This validates the users and allows them to perform any other actions in the account.
- oAuth 2.0: oAuth 2.0 allows users to validate a certain application in Memsource, which consequently allows its continuous communication with Memsource (without the need for further authentication).
In the scenario we're discussing here, we will be using the first option—that is, using the authentication token. This token is necessary for all the following API calls and will not be listed in the example parameters.
To authenticate yourself, use the api/v3/auth/login API call with appropriate parameters (in this case username and password).
- Example Call: https://cloud.memsource.com/web/api/v3/auth/login?userName=USERNAME&password=PASSWORD
- Response: Authentication token.
Step 2: Project Creation, Import, and Assignment
Projects are created using the api/v3/project/create API call, with the mandatory parameters of name, sourceLang, and targetLang.
- Example Call: https://cloud.memsource.com/web/api/v3/project/create?token=AUTHENTICATION TOKEN&name=PROJECT&sourceLang=ja&targetLang=en
- Response: Project UID (e.g. KmtNyVlz1skQd2aMVEipp7)
With the UID obtained in the previous call, it is now possible to add new jobs directly into this newly created project using api/v8/job/create with the mandatory parameters of project, targetLang, and file. When importing a file into a project with the api/v8/job/create endpoint, you don't need to set the source language; it will be automatically set according to the source language set in the project. You will only need to specify the targetLang.
This call can also include linguist as an optional parameter (as used in the example). If this parameter is not included, a separate call (api/v8/job/edit) needs to be used for the purpose of task assignment. The ID of the Linguist that is inserted in the call can be obtained in multiple ways:
- While in Memsource, go to Users and click on the name of the Linguist you wish to assign via the API. The ID will be a part of the URL displayed in the address bar (e.g. https://cloud.memsource.com/web/user/show/94573).
- Use the api/v3/user/getByUserName API call, with the parameter username.
- Use the api/v3/user/list 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.
- Example Call: https://cloud.memsource.com/web/api/v8/job/create?token=AUTHENTICATION TOKEN&targetLang=en&project=KmtNyVlz1skQd2aMVEipp7&linguist=94573
- Response: JobPart ID (e.g. 62399196)
The JobPart ID is then used in api/v8/job/notifyAssignedLinguist, along with the emailTemplate parameter, which represents the ID of the email template that should be used. This can be obtained from the Memsource UI or using api/v2/emailTemplate/list.
- Example Call: token=AUTHENTICATION TOKEN&jobPart=62399196&emailTemplate=7303
- Response: Empty
This is where the translator would start to work in his/her account, in the same way as if the Memsource UI was used. After the job is finished, the PM in charge would receive a notification and the 3rd part of the scenario can be initiated. It is also possible to wait for a callback (please see more details about webhooks) and initiate the 3rd part automatically, but we are listing only a simple example scenario.
Importing Multiple Jobs:
The fastest way to import multiple jobs is to use asynchronous calls.
- Create your jobs.
- Keep checking the status of Asynchronous Request until you get the "OK" response. The first check will be after 5 seconds, and then the interval will increase by 1.5 each time.
- Run Analyse.
- Repeatedly call Asynchronous Request for the "OK" response.
- Run Pre-translate.
- Again, repeatedly call Asynchronous Request for the "OK" response.
Part 3: Project Completion and Download
Once the job (in this case the only one in the project) is completed, it is possible to use api/v3/project/setStatus with the mandatory parameters project and status to change the status of the entire project to Completed. This change is a manual one. However, 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.
- Example Call: https://cloud.memsource.com/web/api/v3/project/setStatus?token=AUTHENTICATION TOKEN&project=KmtNyVlz1skQd2aMVEipp7&status=COMPLETED
- Response: Empty
Once the project is completed (or even before), the API call api/v8/job/getCompletedFile with the parameter jobPart can be used to retrieve the translated content.
- Example Call: https://cloud.memsource.com/web/api/v8/job/getCompletedFile?token=AUTHENTICATION TOKEN&jobPart=62399196
- Response: Binary response with the completed file itself