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:
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 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.
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.
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.
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 |
TBExclusionError |
The operation cannot be performed. The TB is open for exclusive use (e.g. for editing). |
400 Bad Request |
TBReadOnlyError |
The operation cannot be performed. The TB is readonly. |
400 Bad Request |
TBInvalidLanguage |
The TB does not contain the provided language(s). |
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 happened 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": "<seg>Második szegmens</seg>",
"TargetSegment": "<seg>Second segment</seg>"
}
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": "<seg>Második szegmens</seg>",
"Subject": "",
"TargetSegment": "<seg>Second segment</seg>",
"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": "<seg>Második szegmens</seg>",
"TargetSegment": "<seg>Second segment updated</seg>"
}
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": "<seg>Második</seg>"
}
]
}
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": "<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
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": "<seg>Második szegmens</seg>",
"TargetSegment": "<seg>Second segment updated</seg>"
}
}
],
"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