memoQ Server Resources API documentation

The current documentation gives you a general overview of the interface and also includes a reference that details each service with all the operations.

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 accessable 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:

GET https://mqserverurl:8081/memoqserverhttpapi/v1/tms?authToken=fde0f7ed-d585-48ec-a0a9-397aea195ccd
In the response you will get back the list of TMs serialized in JSON:
[
    {
        "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.

Url to login:
POST https://mqserverurl:8081/memoqserverhttpapi/v1/auth/login
In the response you get back the authentication token:
Response body:
{
    "Name": "admin",
    "Sid": "00000000-0000-0000-0001-000000000001",
    "AccessToken": "fde0f7ed-d585-48ec-a0a9-397aea195ccd"
}
You can now attach the token to the URL as a query string parameter:
https://mqserverurl:8081/memoqserverhttpapi/v1/tms?authToken=fde0f7ed-d585-48ec-a0a9-397aea195ccd
or you can put it into the Authorization HTTP header:
Authorization: MQS-API fde0f7ed-d585-48ec-a0a9-397aea195ccd
The API supports all user types that you may use with memoQ server:
  • 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 Temianal. 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"
    }
    

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.

A session can also be manually terminated by calling Logout:
POST https://mqserverurl:8081/memoqserverhttpapi/v1/auth/logout

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.

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.

The general form of an error response is:
{
    "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.

HTTP Status code ErrorCode Message
401 Unauthorized AuthenticationFailed User could not be authenticated.
401 Unauthorized InvalidOrExpiredToken Security token is invalid, has expired or is missing from the request.
401 Unauthorized TooFrequentLogin Too frequent login after logout.
401 Unauthorized NoLicenseAvailable Could not request license.
403 Forbidden Unauthorized User is unauthorized to access the resource.
404 Not Found ResourceNotFound The resource was not found on the server.
404 Not Found EntryNotFound The entry of the resource was not found on the server.
409 Conflict OptimisticConcurrencyError Somebody else has modified the entry.
400 Bad Request TBReadOnlyError The operation cannot be performed. The TB is readonly.
400 Bad Request ReverseLookupNotSupported Reverse lookup is not supported for TM.
400 Bad Request InvalidArgument The arguments are not valid.
400 Bad Request CustomMetaError Custom meta definition was not found.
500 Internal Server Error InternalError An internal error happended on the server. Check the log for details.

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.

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
Request:
POST memoqserverhttpapi/v1/auth/login
{
    username: "admin",
    password: "secret",
    LoginMode: "0"
}
Response:
{
    "Name": "admin",
    "Sid": "00000000-0000-0000-0001-000000000001",
    "AccessToken": "803be2ac-f4a1-4b47-abea-8b12f2a172d8"
}
List all TMs
Request:
GET memoqserverhttpapi/v1/tms?authToken=803be2ac-f4a1-4b47-abea-8b12f2a172d8
Response:
[
    {
        "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
Request:
GET memoqserverhttpapi/v1/tms/2433ea4e-0ea6-4339-9c1f-f84bce41ad3b?authToken=803be2ac-f4a1-4b47-abea-8b12f2a172d8
Response:
{
    "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
Request:
POST memoqserverhttpapi/v1/tms/2433ea4e-0ea6-4339-9c1f-f84bce41ad3b/entries/create?authToken=803be2ac-f4a1-4b47-abea-8b12f2a172d8
{
    "Modifier": "testuser",
    "SourceSegment": "Második szegmens",
    "TargetSegment": "Second segment"
}
Get an entry of a TM Request:
GET memoqserverhttpapi/v1/tms/2433ea4e-0ea6-4339-9c1f-f84bce41ad3b/entries/0?authToken=803be2ac-f4a1-4b47-abea-8b12f2a172d8
Response:
{
    "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": "Második szegmens",
    "Subject": "",
    "TargetSegment": "Second segment",
    "CustomMetas": []
}
Update an entry of a TM
Request:
POST memoqserverhttpapi/v1/tms/2433ea4e-0ea6-4339-9c1f-f84bce41ad3b/entries/0/update?authToken=803be2ac-f4a1-4b47-abea-8b12f2a172d8
{
    "Modifier": "testuser",
    "Modified": "2015-10-15T12:45:49.209Z",
    "SourceSegment": "Második szegmens",
    "TargetSegment": "Second segment updated"
}
Lookup for a segment in a TM
Request:
POST memoqserverhttpapi/v1/tms/2433ea4e-0ea6-4339-9c1f-f84bce41ad3b/lookupsegments?authToken=803be2ac-f4a1-4b47-abea-8b12f2a172d8
{
    "Segments": [
        {
            "Segment": "Második"
        }
    ]
}
Response:
{
    "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": "Második szegmens",
                        "Subject": "",
                        "TargetSegment": "Second segment updated",
                        "CustomMetas": []
                    }
                }
            ]
        }
    ]
}
Concordance search in a TM
Request:
POST memoqserverhttpapi/v1/tms/2433ea4e-0ea6-4339-9c1f-f84bce41ad3b/concordance?authToken=803be2ac-f4a1-4b47-abea-8b12f2a172d8
{
    "SearchExpression": ["második"]
}
Response:
{
    "ConcResult": [
        {
            "ConcordanceTextRanges": [
                {
                "Length": 7,
                "Start": 0
                }
            ],
            "ConcordanceTranslationRanges": [],
            "Length": 7,
            "StartPos": 0,
            "TMEntry": {
                "SourceSegment": "Második szegmens",
                "TargetSegment": "Second segment updated"
            }
        }
    ],
    "ConcTransResult": [],
    "Errors": [],
    "TotalConcResult": 1
}
Delete an entry of a TM
Request:
POST memoqserverhttpapi/v1/tms/2433ea4e-0ea6-4339-9c1f-f84bce41ad3b/entries/0/delete?authToken=803be2ac-f4a1-4b47-abea-8b12f2a172d8

2. API Reference

2.1. Authentication

Responsible for user authentication. Enables users to login to and log out from memoQ server.

APIDescription
POST v1/auth/loginLogs in to memoQ server with a memoQ server, Windows or Language Terminal user. It creates a session for the user on memoQ server.
POST v1/auth/logoutLogs out the current user from memoQ server. It removes the user's session from memoQ server.

2.2. TranslationMemory

Responsible for translation memory related actions.

APIDescription
GET v1/tms?srcLang={srcLang}&targetLang={targetLang}Gets a list of the translation memories on memoQ server. Filters the TMs by the specified source or target language.
GET v1/tms?tmGuid={tmGuid}Gets the translation memory by the specified Guid.
GET v1/tms/{tmGuid}Gets the translation memory by the specified Guid.
GET v1/tms/{tmGuid}/custommetaschemeGets the custom meta scheme of the translation memory specified by a Guid.
POST v1/tms/{tmGuid}/concordancePerforms a concordance search in the translation memory specified by a Guid.
POST v1/tms/{tmGuid}/lookupsegmentsPerforms a lookup operation in the translation memory specified by a Guid.
GET v1/tms/{tmGuid}/entries/{entryId}Gets the translation memory entry specified by a TM Guid and an entry id.
POST v1/tms/{tmGuid}/entries/{entryId}/updateUpdates the translation memory entry specified by a TM Guid and an entry id.
POST v1/tms/{tmGuid}/entries/createCreates a translation memory entry in the TM specified by a Guid.
POST v1/tms/{tmGuid}/entries/{entryId}/deleteDeletes the translation memory entry specified by a TM Guid and an entry id.

2.3. Termbase

Responsible for termbase related actions.

APIDescription
GET v1/tbs?lang[0]={lang[0]}&lang[1]={lang[1]}Gets a list of the termbases on memoQ server. Filters the TBs by the specified languages.
GET v1/tbs?tbGuid={tbGuid}Gets the termbase by the specified Guid.
GET v1/tbs/{tbGuid}Gets the termbase by the specified Guid.
GET v1/tbs/{tbGuid}/metadefinitionsGets the meta definitions of the termbase specified by a Guid.
POST v1/tbs/{tbGuid}/lookuptermsPerforms a lookup operation in the termbase specified by a Guid.
POST v1/tbs/{tbGuid}/searchLooks up the given expression in the termbase.
GET v1/tbs/{tbGuid}/entries/{entryId}Gets the termbase entry specified by a TB Guid and an entry id.
POST v1/tbs/{tbGuid}/entries/{entryId}/updateUpdates the termbase entry specified by a TB Guid and an entry id.
POST v1/tbs/{tbGuid}/entries/create?returnNewEntry={returnNewEntry}Creates a termbase entry in the TB specified by a Guid.
POST v1/tbs/{tbGuid}/entries/{entryId}/deleteDeletes the termbase entry specified by a TB Guid and an entry id.
GET v1/tbs/{tbGuid}/entries/{entryId}/entrymetas/{metaname}Gets the image of a termbase entry's entry level meta property.
GET v1/tbs/{tbGuid}/entries/{entryId}/languagemetas/{metaname}Gets the image of a termbase entry's language level meta property.
GET v1/tbs/{tbGuid}/entries/{entryId}/languagemetas/{language}/{metaname}Gets the image of a termbase entry's language level meta property.
GET v1/tbs/{tbGuid}/entries/{entryId}/termmetas/{metaname}Gets the image of a termbase entry's term level meta property.
GET v1/tbs/{tbGuid}/entries/{entryId}/termmetas/{termId}/{metaname}Gets the image of a termbase entry's term level meta property.
POST v1/tbs/{tbGuid}/entries/{entryId}/entrymetas/{metaname}Sets the image of a termbase entry's entry level meta property.
POST v1/tbs/{tbGuid}/entries/{entryId}/languagemetas/{metaname}Sets the image of a termbase entry's language level meta property.
POST v1/tbs/{tbGuid}/entries/{entryId}/languagemetas/{language}/{metaname}Sets the image of a termbase entry's language level meta property.
POST v1/tbs/{tbGuid}/entries/{entryId}/termmetas/{metaname}Sets the image of a termbase entry's term level meta property.
POST v1/tbs/{tbGuid}/entries/{entryId}/termmetas/{termId}/{metaname}Sets the image of a termbase entry's term level meta property.