Memsource REST API

Memsource REST API—How to Use Memsource APIs

Due to Memsource Legacy APIs being deprecated in the near future, this article serves as an adapted version of the basic tutorial on how to work with Memsource APIs.

 

The article below will provide a simple API scenario with sample API calls and instructions on 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 an 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 REST API documentation to find out 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 Postman or any similar application that allows you to submit a GET request and a POST API request with a JSON body.

Description

The scenario discussed in this article will cover the following process:
The user will authenticate themselves 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 the finished document from the project.

Method

In the Legacy format, both GET and POST methods worked in the majority of the API calls. This has now changed, and 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) will result in an unsuccessful API call.

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.

Postman.png

Step 1: Authentication

There are 2 possible ways to authenticate: 

  1. 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.
  2. 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 api2/v1/auth/login API call with appropriate parameters (in this case username and password).

  • 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

Projects are created using the api2/v1/projects API call, with the mandatory parameters of name, sourceLang, and targetLangs.

  • Method: POST
  • Request URL: https://cloud.memsource.com/web/api2/v1/projects?token=Authentication token
  • Request body:
{
"name":"My project",
"sourceLang":"en",
"targetLangs":[
"de","fr"
]
}
  • Response: Project UID (e.g. KmtNyVlz1skQd2aMVEipp7)

Job Creation

With the UID obtained in the previous call, it is now possible to add new jobs directly into this newly created project using api2/v1/projects/{projectUid}/jobs.

The expression {projectUid} serves as a placeholder in the request URL where the obtained Project UID should be inserted. With the Create Job API call, it is also necessary to change the Headers of the request to match the ones required by Memsource (in other calls, Postman will automatically add appropriate headers to the request).

All the import parameters need to be inserted into a custom Memsource header.

The Content-Disposition header needs to include the filename in a pre-defined format in order for Memsource to process the import request correctly.

  • Method: POST
  • Request URL: https://cloud.memsource.com/web/api2/v1/projects/KmtNyVlz1skQd2aMVEipp7/jobs?token=Authentication token
  • (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)

This call can also include assignments as an optional parameter. If this parameter is not included, a separate call (/api2/v1/projects/{projectUid}/jobs/{jobUid}) needs to be used for the purpose of task assignment. The ID of the Provider that is inserted in the call can be obtained in multiple ways:

  1. While in Memsource, go to Users and click on the name of the Provider 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).
  2. Use the /api2/v1/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, which represents the ID of the email template that should be used. This can be obtained from the Memsource UI or using /api2/v1/emailTemplates.

  • Request URL: https://cloud.memsource.com/web/api2/v1/projects/KmtNyVlz1skQd2aMVEipp7/jobs/notifyAssigned?token=Authentication token
  • Response: Empty

This is where the translator would start to work in their account, in the same way they would if the Memsource UI was being 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.

Part 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?token=Authentication token
  • Response: Binary response with the completed file itself

Once the job (in this case the only one in the project) is completed, it is possible to use /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. 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.

  • Method POST
  • Request URL: https://cloud.memsource.com/web/api2/v1/projects/KmtNyVlz1skQd2aMVEipp7/setStatus?token=Authentication token
  • Request body:
{
"status": "COMPLETED"
}
  • Response: Empty