The current documentation gives you a general overview of the interface and also includes a reference that details each service with all the operations.
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:
The following operations are supported for TBs:
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"
}
]
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.
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:
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.
{
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.
{
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".
{
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
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).
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.
For security reasons the API only supports HTTPS.
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 |
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. |
Currently the API contains three services. Each of them has a dedicated URL and a version number. Version numbers can vary per services.
Services:
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
Responsible for user authentication. Enables users to login to and log out from memoQ server.
|
API |
Description |
|
POST v1/auth/login |
Logs 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/logout |
Logs out the current user from memoQ server. It removes the user's session from memoQ server. |
Responsible for translation memory related actions.
|
API |
Description |
|
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}/custommetascheme |
Gets the custom meta scheme of the translation memory specified by a Guid. |
|
POST v1/tms/{tmGuid}/concordance |
Performs a concordance search in the translation memory specified by a Guid. |
|
POST v1/tms/{tmGuid}/lookupsegments |
Performs a lookup operation in the translation memory specified by a Guid. 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. |
|
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}/update |
Updates the translation memory entry specified by a TM Guid and an entry id. |
|
POST v1/tms/{tmGuid}/entries/create |
Creates a translation memory entry in the TM specified by a Guid. |
|
POST v1/tms/{tmGuid}/entries/{entryId}/delete |
Deletes the translation memory entry specified by a TM Guid and an entry id. |
Responsible for termbase related actions.
|
API |
Description |
|
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}/metadefinitions |
Gets the meta definitions of the termbase specified by a Guid. |
|
Performs a lookup operation in the termbase specified by a Guid. |
|
|
POST v1/tbs/{tbGuid}/search |
Looks 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}/update |
Updates 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}/delete |
Deletes 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. |
© Copyright 2000-2023 COGITO SOFTWARE CO.,LTD. All rights reserved
