Memsource API

From Memsource
Jump to: navigation, search


New Memsource REST APIs

Memsource is introducing REST APIs. Please refer to this documentation to view the new APIs. The information in the following article is currently being updated for REST APIs and will be published shortly. For further information, please contact Memsource Support.

(Updated 25 October 2017)

Introduction

Memsource Cloud offers a set of API calls which allow for:

  • Integration of Memsource and any third party software (translation management tool, CMS, etc.)
  • Development of a translator's workbench. Actually, both Memsource Editor and Memsource Web Editor are built on top of public APIs.
  • Creation of a brand new tool or service which uses Memsource in its backend.

API limits for Editions

API is available for all paid editions with following limits:

Edition Max. API Calls Daily
Ultimate & BIZ Ultimate Unlimited
Team & BIZ Team 2000
Team Start & BIZ Start 1000
Freelancer 500
Personal 0


The limits are checked every 30 minutes and reset at 0:00 GMT. User can set an email notification when 80% or 100% of the limit is reached in Cloud Setup > API statistic. The API response when limit is exceeded is ApiLimitReached.

Getting Started

The free Memsource Developer edition is designed for use as a sandbox for API development. Users can use the Chrome Postman application to learn how Memsource APIs work, and to test them.

It is essential to learn Memsource procedures and workflow to be able to understand and use Memsource APIs. Please follow the Getting Started with Memsource Cloud manual and/or a short video at My 1st Project for more info about how to work in Memsource.

The basic workflow is:

  1. create TM, TB, and a machine translation engine (if you intend to use them)
  2. create a project with the TM/TB/machine translation engine attached (if needed),
  3. upload your file for translation (create a job) to the project
  4. you can then analyze, pre-translate or assign the job to the linguist.

The Memsource API is intended to be used by developers familiar with the general API language. Please follow the instruction below.

Technology

Memsource APIs are all client-server based where Memsource Cloud is the server and a third party software or an editor is the client. HTTPS protocol is used as a transport media for communication between the client and the server, using either GET or POST method.

The API parameters are encoded using multipart/form-data or application/x-www-form-urlencoded when submitting parameters in a HTTP body. This is a preferred way of passing parameters due to security reasons. Alternatively, you can pass parameters in a query string (files cannot be uploaded this way), but it is not recommended.

Memsource accepts only UTF-8 encoded characters in the API calls.

The server responses are sent to the client as JSON data structures. Both HTTPS and JSON are plain but robust and straightforward protocols. HTTPS/JSON are well-supported on a variety of environments including command-line programs written in C, enterprise systems written in Java, and modern web sites written in Python, Ruby, or Groovy.

API Example

The complete API reference can be found below. This is only an example of how to read the reference.

action: project/create
    token                       string
    name                        string                             
    sourceLang                  lang
    targetLang                  list(lang)
    client                      string                         O
    domain                      string                         O
    due                         datetime                       O
    machineTranslationType      enum(MachineTranslationType)   O(Google)

response: JSON
    {
      "id": 238                 // id of the project
    }

When making an HTTP request, you have to append the action name to the base URL which has the form of https://cloud.memsource.com/web/api/VERSION_NUMBER, where VERSION_NUMBER is replaced with v2, v3, etc. The table below the action name describes the list of parameters for the action. The first column contains the names of the parameters. The second column specifies data types and the third column may contain additional flags describing a parameter:

  • M(value) - only for lists, maximum number of items that can be passed in the list
  • N - "null" can be used to explicitly set the data to null (useful in edit API calls)
  • O - optional parameter
  • O(value) - optional parameter with the default value


The URL and parameters may look like:

https://cloud.memsource.com/web/api/v2/project/create

token=30-d987eb187ecf4282049dd7e830c14f57&name=My%20Project&sourceLang=en&targetLang=de&targetLang=ru&client=My%20Client

When all the parameters are correct and the user is authorized to make the call, the 200 code is returned in the HTTP status code and some additional data are usually returned. In this case, it will be a JSON structure. In other API calls it may be the binary data of a downloaded file.

Error Handling

If there is a problem when handling an API request, the following JSON structure will be returned. The error code will always be present, the detailed description may be null.

{
  "errorCode": "InvalidArguments",
  "errorDescription": "Required argument \"password\" of type \"string\" is missing."
}

An error response can be detected by reading the HTTP status code of the response. If an error occurs, it will never be set to 200. The status code is 400 for wrong or missing parameters, 401 or 403 for authentication or authorization problems. See the list of error codes for more details.

Reporting problems to Memsource support

When reporting problem to Memsource support, please make sure your report includes:

  • API endpoint
  • parameters
  • time (and timezone)
  • response
  • Memsource-Action-Id of the response

Authentication

Most of the API calls require an authenticated Memsource user. The APIs do not use any special user accounts. Each API can be called on behalf of any existing user (using their username and password). Before calling any API that requires an authenticated user, you have to call auth/login API to obtain an authentication token. Such a token is valid for 24 hours and can be used for all subsequent calls (please, do not acquire a new token for every call). See the reference for more details about the authentication.

OAuth 2.0

OAuth 2.0 can be set and managed in Memsource Cloud Setup > Integration

Auth URL:

/web/oauth/authorize

Token URL:

/web/oauth/token

API Reference

Synchronous APIs

Asynchronous APIs

Asynchronous APIs should always be preferred to their synchronous counterparts. If you call synchronous APIs, there is a chance of receiving timeout expired responses when processing large batches of files or even a single huge file. Synchronous APIs should only be used for small files and small scale integration with Memsource.

Polling

After you call an asynchronous API, you will receive an instant response including the identifier request. You will use this identifier to check the status of the request by calling getAsyncRequest and checking asyncResponse field. This polling approach can lead to a number of getAsyncRequest calls before you actually receive asyncResponse as not null.

Callbacks

As a response to the drawbacks of the polling approach to asynchronous requests, we have introduced support for callbacks in all asynchronous APIs. When calling an asynchronous request, you specify a URL (in callbackUrl parameter) that will be requested from our side just after the work initiated by the asynchronous request is finished.

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 (same as when calling getAsyncRequest),
  • detailed information about the result of the action (for example a full analysis or jobs details).
{
  "asyncRequest": {
   ...
  }
  "analyse": {
   ...
  }
}

If the callback URL is not accessible, the request will be repeated from our side after 2 minutes, then 4 minutes, 8 minutes, 16 minutes, and then after 30 minutes up to a total number of 10 retries.

Your callback URL must respond with the 200 OK HTTP status code to be considered successful on our side.

List of Asynchronous APIs

Data Types

Deprecated APIs

Please note that the old address cloud1.memsource.com was also deprecated. Only cloud.memsource.com should be used.

Webhooks

Webhook is a way how Memsource Cloud can notify a third party system about certain events (for example, a job status has been changed). When you are logged in Memsource Cloud, webhooks can be configured in Setup | Integrations section. Webhook is an arbitrary URL which can handle HTTP POST requests.

The requests are treated in the same way as callbacks in asynchronous APIs. A JSON data structure is passed in the body of a POST request.

{
  event: "JOB_STATUS_CHANGED",
  jobParts: [
    ...
  ]
}


Events

  • Job status has changed
{
"jobParts": [
  {
    "id": 9,
    "uid": "ipmdz5p0sagqcOYaijTZU2",
    "internalId": "4",
    "task": "SEfSaenvqFgctE1I0_dc1",
    "fileName": "en.txt",
    "targetLang": "af",
    "workflowLevel": 1,
    "status": "NEW",
    "wordsCount": 2,
    "beginIndex": 0,
    "endIndex": 1,
    "isParentJobSplit": false,
    "dateDue": null,
    "dateCreated": "2016-11-02T17:06:54Z",
    "project": {
      "id": 2
    },
    "assignedTo": [
      {
        "vendor": {
          "id": 1,
          "name": "Abc",
          "vendorToken": "4-ifos0-CAqPo"
        }
      },
      {
        "linguist": {
          "id": 3,
          "firstName": "Admin",
          "lastName": "Admin",
          "userName": "admin",
          "email": "admin@example.com",
          "role": "ADMIN",
          "timezone": "Europe/London",
          "active": true,
          "deleted": false,
          "terminologist": false,
          "dateCreated": "2016-10-11T07:43:22Z"
        }
      }
    ]
  }
],
"event": "JOB_STATUS_CHANGED"
}
  • Job Assigned
{
"jobParts": [
  {
    "id": 9,
    "uid": "ipmdz5p0sagqcOYaijTZU2",
    "internalId": "4",
    "task": "SEfSaenvqFgctE1I0_dc1",
    "fileName": "en.txt",
    "targetLang": "af",
    "workflowLevel": 1,
    "status": "NEW",
    "wordsCount": 2,
    "beginIndex": 0,
    "endIndex": 1,
    "isParentJobSplit": false,
    "dateDue": null,
    "dateCreated": "2016-11-02T17:06:54Z",
    "project": {
      "id": 2
    },
    "assignedTo": [
      {
        "vendor": {
          "id": 1,
          "name": "Abc",
          "vendorToken": "4-ifos0-CAqPo"
        }
      },
      {
        "linguist": {
          "id": 3,
          "firstName": "Admin",
          "lastName": "Admin",
          "userName": "admin",
          "email": "admin@example.com",
          "role": "ADMIN",
          "timezone": "Europe/London",
          "active": true,
          "deleted": false,
          "terminologist": false,
          "dateCreated": "2016-10-11T07:43:22Z"
        }
      }
    ]
  }
],
"event": "JOB_ASSIGNED"
}
  • Job created
{
 "jobParts": [
   {
     "id": 9,
     "uid": "ipmdz5p0sagqcOYaijTZU2",
     "internalId": "4",
     "task": "SEfSaenvqFgctE1I0_dc1",
     "fileName": "en.txt",
     "targetLang": "af",
     "workflowLevel": 1,
     "status": "NEW",
     "wordsCount": 2,
     "beginIndex": 0,
     "endIndex": 1,
     "isParentJobSplit": false,
     "dateDue": null,
     "dateCreated": "2016-11-02T17:06:54Z",
     "project": {
       "id": 2
     },
     "assignedTo": [
       {
         "vendor": {
           "id": 1,
           "name": "Abc",
           "vendorToken": "4-ifos0-CAqPo"
         }
       },
       {
         "linguist": {
           "id": 3,
           "firstName": "Admin",
           "lastName": "Admin",
           "userName": "admin",
           "email": "admin@example.com",
           "role": "ADMIN",
           "timezone": "Europe/London",
           "active": true,
           "deleted": false,
           "terminologist": false,
           "dateCreated": "2016-10-11T07:43:22Z"
         }
       }
     ]
   }
 ],
 "event": "JOB_CREATED"
}