memoQ Server Resources API documentation

1. General overview

1.1. Introduction

memoQ Server Resources API is a REST style interface for a set of functionalities provided by memoQ server. This interface makes memoQ server be accessible from many kinds of client applications let they be a desktop, mobile or web applications. The client only needs to send simple, easy-to-assemble HTTP requests and consume the responses. Information traveling back and forth between the client and the server is typically JSON serialized. Currently the API supports manipulating translation memories (TM) and termbases (TB).

The following operations are supported for TMs:

• Get the list of TMs in memoQ server
• Get detailed information about a certain TM
• Perform a concordance search in a TM
• Lookup for segments in a TM
• Get, update, create or delete entries in a TM

The following operations are supported for TBs:

• Get the list of TBs in memoQ server
• Get detailed information about a certain TB
• Lookup for terms in a TB
• Get, update, create or delete entries in a TB
• Get the metadata schema of a TB

For example to get the list of TMs you need to login for first (see later) to get an authentication token and then simply send an HTTP GET request to the following URL:

[
    {
        "AccessLevel": 1,
        "Client": "client 1",
        "Domain": "domain 1",
        "Subject": "subject 1",
        "Project": "project 1",
        "NumEntries": 0,
        "FriendlyName": "Test TM 1",
        "SourceLangCode": "eng",
        "TargetLangCode": "hun",
        "TMGuid": "dea956bd-52ce-4fd5-a666-cb28ddefb090",
        "TMOwner": "csiri"
    },
    {
        "AccessLevel": 1,
        "Client": "client 2",
        "Domain": "domain 2",
        "Subject": "subject 2",
        "Project": "project 2",
        "NumEntries": 0,
        "FriendlyName": "Test TM 2",
        "SourceLangCode": "ger",
        "TargetLangCode": "spa",
        "TMGuid": "2433ea4e-0ea6-4339-9c1f-f84bce41ad3b",
        "TMOwner": "csiri"
    }
]
                        

1.2. Data representation

The parameters of the API operations may come from two places. Some parameters are part of the URL, others are placed into the body of the request. The API reference explicitly specifies all possible parameters (including their expected places) and return types for all the operations. As a rule parameters that are used to identify a resource (e.g. a TM entry) are part of the URL and all other parameters (if there are any) are put into the body. The authentication token is an exception as it is a general parameter. You can put it into the URL, though the best practice is to have it in the HTTP header (see later).

The API supports JSON serialization as data representation in the HTTP body for both requests and responses. That means data that is posted by the client should be JSON serialized. Data that is returned by the server is also JSON serialized.

The client needs to set the Accept and the Content-type HTTP headers properly.

• "Accept: application/json" reflects that the client expects the response to be JSON serialized.
• "Content-type: application/json" means that the data posted by the client is JSON serialized.

1.3. Security

1.3.1. Authentication and session handling

The operations of the API can only be accessed after a successful login with a memoQ server user. The login will provide you with an authentication token that you will need to supply in all forthcoming requests. Technically this access token identifies your user session to memoQ server. The token can either be included in the URL as a query string parameter or it can also be put into the Authorization HTTP header.

To login to memoQ server you need to send an HTTP POST request to the following URL with a request body containing the credentials and the type of authentication that you want to use.

{
    "Name": "admin",
    "Sid": "00000000-0000-0000-0001-000000000001",
    "AccessToken": "fde0f7ed-d585-48ec-a0a9-397aea195ccd"
}

• MemoQServerUser (0): login with the username and the password of a user that was created on memoQ server.

  Example request:

  {
      username: "admin",
      password: "secret",
      LoginMode: "0"
  }
  

• WindowsUser (1): login by specifying the username and the password of a user that was synchronized from AD or SAM.

  Example request:

  {
      username: "mydomain\testuser",
      password: "secret",
      LoginMode: "1"
  }
  

• LTUser (2): single sign-on login with a user synchronized from Language Terminal. The login request should contain the CAS (https://wiki.jasig.org/display/CAS/Home) Service Ticket for service URL "http://memoqserver".

  Example request:

  {
      LTST: "<service ticket>",
      LoginMode: "2"
  }
  

• OidcUser (3): customers can create applications to do operations (like lookup, adding term, or TM entries, etc.) on a memoQ server's TMs and TB's through the Resources API. It provides them the possibility to do this through an external ID provider.

  Example request:

  {
      LoginId: "VFJ3MDRaQVZMZG9JSnhOQVNMMjlIY3VuV2VvZ0JRaVJCYURvcFhSWlhPYlUzWW5udG8",
      LoginMode: "3"
  }
  

The user’s session expires and the token gets invalid after some time of inactivity. The client is notified about it by a dedicated error (ErrorCode: InvalidOrExpiredToken). After session expiry a new login is required.

1.3.2. Authorization

Access to resources (TMs and TBs) are controlled by the group memberships of the API users. memoQ sports two built-in groups, called “Resource lookup via API/plugins” and “Resource update via API/plugins”. Membership in these two groups automatically grants lookup and update rights to ALL resources on the memoQ server.

It is possible to override this behaviour and enforce the default resource access policy by specifying the following flag in the HttpApiConfig.xml file:

<DisableAuthorizationPolicyOverride>true</DisableAuthorizationPolicyOverride>

When a user is not authorized to access the requested resource she gets back a dedicated error (ErrorCode: Unauthorized).

1.3.3. Licensing

Accessing the API requires Translator light or Translator Pro licenses. First it tries to retrieve a Translator light license and when there are no free Translator light ones it tries to get a Translator Pro. When there are neither free light nor pro licenses in the pool the user will get a dedicated error (ErrorCode: NoLicenseAvailable) and won’t be able to use the API until a license is returned.

Handling licenses is transparent for clients, memoQ server requests licenses in an on-demand manner and releases them after some time of inactivity. This timeout is shorter than the session timeout. The lifecycle of licenses and a sessions are not bound together. So you should be prepared for licensing errors in all requests.

1.3.4. HTTPS

For security reasons the API only supports HTTPS.

1.4. Error handling

The success of the request is reflected by the HTTP status code of the response. In case of success it is 2xx (200 OK, 201 Created or 204 No Content). Otherwise there was an error during the execution of the request. In case of errors the response also contains a JSON structure about the error that gives you more information than the HTTP status code.

{
    "ErrorCode": "InvalidOrExpiredToken",
    "Message": "Security token is invalid or has expired."
}

The ErrorCode is a string constant that identifies the problem and the Message is some English (non-localized) textual information that gives you more details.

The following table summarizes all the errors that an API client should be prepared for.

1.5. Versioning of services

Currently the API contains three services. Each of them has a dedicated URL and a version number. Version numbers can vary per services.

• Authentication service
  URL: /memoqserverhttpapi/v1/auth
  Current version: v1
• TranslationMemory service
  URL: /memoqserverhttpapi/v1/tms
  Current version: v1
• TermBase service
  URL: /memoqserverhttpapi/v1/tbs
  Current version: v1

1.6. Examples

The following example shows some operations on a TM.

Login to memoQ server

{
    username: "admin",
    password: "secret",
    LoginMode: "0"
}

{
    "Name": "admin",
    "Sid": "00000000-0000-0000-0001-000000000001",
    "AccessToken": "803be2ac-f4a1-4b47-abea-8b12f2a172d8"
}

List all TMs

[
    {
        "AccessLevel": 1,
        "Client": "client 1",
        "Domain": "domain 1",
        "Subject": "subject 1",
        "Project": "project 1",
        "NumEntries": 0,
        "FriendlyName": "Test TM 1",
        "SourceLangCode": "eng",
        "TargetLangCode": "hun",
        "TMGuid": "dea956bd-52ce-4fd5-a666-cb28ddefb090",
        "TMOwner": "csiri"
    },
    {
        "AccessLevel": 1,
        "Client": "client 2",
        "Domain": "domain 2",
        "Subject": "subject 2",
        "Project": "project 2",
        "NumEntries": 0,
        "FriendlyName": "Test TM 2",
        "SourceLangCode": "ger",
        "TargetLangCode": "spa",
        "TMGuid": "2433ea4e-0ea6-4339-9c1f-f84bce41ad3b",
        "TMOwner": "csiri"
    }
]

Get information about a TM

{
    "AccessLevel": 1,
    "Client": "client 2",
    "Domain": "domain 2",
    "Subject": "subject 2",
    "Project": "project 2",
    "NumEntries": 0,
    "FriendlyName": "Test TM 2",
    "SourceLangCode": "ger",
    "TargetLangCode": "spa",
    "TMGuid": "2433ea4e-0ea6-4339-9c1f-f84bce41ad3b",
    "TMOwner": "csiri"
}

Add a new entry to a TM

{
    "Modifier": "testuser",
    "SourceSegment": "<seg>Második szegmens</seg>",
    "TargetSegment": "<seg>Second segment</seg>"
}

Get an entry of a TM

{
    "Client": "",
    "ContextID": null,
    "Created": "2015-10-15T12:45:49.209Z",
    "Creator": "admin",
    "Document": "",
    "Domain": "",
    "FollowingSegment": "",
    "Key": 0,
    "Modified": "2015-10-15T12:45:49.209Z",
    "Modifier": "admin",
    "PrecedingSegment": "",
    "Project": "",
    "SourceSegment": "<seg>Második szegmens</seg>",
    "Subject": "",
    "TargetSegment": "<seg>Second segment</seg>",
    "CustomMetas": []
}

Update an entry of a TM

{
    "Modifier": "testuser",
    "Modified": "2015-10-15T12:45:49.209Z",
    "SourceSegment": "<seg>Második szegmens</seg>",
    "TargetSegment": "<seg>Second segment updated</seg>"
}

Lookup for a segment in a TM

{
    "Segments": [
        {
            "Segment": "<seg>Második</seg>"
        }
    ]
}

{
    "Result": [
        {
            "TMHits": [
                {
                    "MatchRate": 58,
                    "TransUnit": {
                        "Client": "",
                        "ContextID": null,
                        "Created": "0001-01-01T00:00:00Z",
                        "Creator": "",
                        "Document": "",
                        "Domain": "",
                        "FollowingSegment": "",
                        "Key": 0,
                        "Modified": "2015-10-15T12:52:37.781Z",
                        "Modifier": "admin",
                        "PrecedingSegment": "",
                        "Project": "",
                        "SourceSegment": "<seg>Második szegmens</seg>",
                        "Subject": "",
                        "TargetSegment": "<seg>Second segment updated</seg>",
                        "CustomMetas": []
                    }
                }
            ]
        }
    ]
}

Remark: For performance reasons the operation currently does not return valid values in the context related fields (ContextID, PrecedingSegment, FollowingSegment) of the TransUnit field of the returned TMHits object. These pieces of information can be retrieved by issuing an extra request getting the specific TM entry based on its key.

Concordance search in a TM

{
    "SearchExpression": ["második"]
}

{
    "ConcResult": [
        {
            "ConcordanceTextRanges": [
                {
                "Length": 7,
                "Start": 0
                }
            ],
            "ConcordanceTranslationRanges": [],
            "Length": 7,
            "StartPos": 0,
            "TMEntry": {
                "SourceSegment": "<seg>Második szegmens</seg>",
                "TargetSegment": "<seg>Second segment updated</seg>"
            }
        }
    ],
    "ConcTransResult": [],
    "Errors": [],
    "TotalConcResult": 1
}

Delete an entry of a TM