Table of Contents

    API

    Mock Server

    Use this URL to access a mockup of the API server. Your traffic will be recorded and compared to the documentation. You'll find your traffic analysis in the inspector or directly here in the documentation, right next to each resource.

KantanMT API v2.0

Overview

The KantanMT API allows customers to interact with the KantanMT translation facility as an on-demand web service. Users can submit individual segments or groups of segments for translation, and receive those translations immediately, in contrast to the browser-based KantanMT experience, which performs much larger translation volumes in a “batch” or “job-based” workflow. The API operates as a REST web service, meaning that a client program needs only to be able to perform HTTP GET requests to interact with the API. Thus, the API is not limited to interacting with clients developed using a particular programming language or operating system.

Architecture

The KantanMT API operates as a multi-instance system, whereby each user is allocated servers which host specified client profiles. These servers use the client profiles to translate user-supplied segments and return the translations. This allocation is completely transparent to the end-user, with the API behaving as if all requests from all users were serviced by the same endpoint. Each API instance is isolated from every other instance, meaning that a user can expect a certain minimum level of performance, and offers the security that they and only they will be served translations from their own client-profiles.

Data Formats

The API processes requests in the form of URLs qualified with a set of parameters which tell it what operation is to be performed and contain any data needed to accomplish those operations. Upon completion or error, the API responds to requests using the JSON data format, which must be parsed on the client-side in order to extract information from the response. JSON parsers exist for most popular programming languages, either as features of those languages, or available as third party libraries.

API Usage

All API requests require the use of an authorisation token, which appears on the “API” tab on the dashboard in “My Client Profiles” if you have been authorised to use the API. Each API token is associated with exactly one user account.

API requests made using HTTP GET take the form http://www.kantanmt.com/api/command/token/parameters where “token” is the authorisation token provided by KantanMT, “command” is the particular operation to be performed, and “parameters” is a sequence of zero or more parameters, delimited by forward slashes, which the preceding command uses to perform its specific task.

Requests made using HTTP POST take the form http://www.kantanmt.com/api/command, with the request parameters encoded in the POST body itself.

Starting And Stopping

As described previously, the API is a multi-instance system, with each user’s API instance running on its own server. User instances do not run indefinitely, and must be explicitly started and stopped. The API can be started directly using a HTTP GET request. Depending on the word count in your client profile, start-ups can take a few minutes, so the API can be queried to view its current status. After a user starts their API, they can periodically poll it, and when the API signals that it’s running, the user can begin submitting content for translation. When the translation session is complete, they can then shut down the API. Like start-up, this can take several minutes, so the API can be polled to determine when shut down completes.

INIT

“init” starts an API instance and configures it to host a specified client profile, or returns a JSON message indicating that the instance is already started. This request should be made as a HTTP GET request. Init can take a few minutes to complete, so client applications should send an init request, and periodically poll the API status using the “query” command, described below, until the API signals it is online, at which point translation can begin. Alternatively, users can use the KantanMT website to view the status of the API launch, as it will appear as a job in their jobs list with a job name of “API Launch.”

GET

/api/init/{token}/{ProfileName}

Launch an API instance using a specified profile name

Response

200 (OK)
Content-Type: application/json
{"response":{"type":"status","body":{"state":"initialising","profile":"ProfileName"}}}

QUERY

“query” allows users to retrieve information about their account, such as the status of API instances associated with their user account, or a list of client profiles associated with their account. It also allows users to query the status of a job associated with their account. The query command should be executed as a HTTP GET request.

GET

/api/query/{token}/profiles

Retrieve the list of clients profiles for the account associated with token, including their name, source and target languages, BLEU, F-Measure and TER scores, unique, non-unique and translated wordcounts, and the stock engine assigned to the profile if one exists.

Response

200 (OK)
Content-Type: application/json
{"response":{"type":"profiles","body":{"profiles":[{"name":"Default-Profile","src":"en","trg":"fr","stockengine":"","fmeasure":"0.495812","bluescore":"23.55","ter":"0.675115","wc":"222265","uniquewc":"17518","processedwc":"147029"}]}}}

GET

/api/query/{token}/status/{profileName}

Query the API status of ProfileName, for the user account associated with token

Response

200 (OK)
Content-Type: application/json
{"response":{"type":"status","body":{"state":"running","profile":"ProfileName"}}} 

GET

/api/query/{token}/job/{jobid}

Query the status of the job with the specified id for the user account associated with token

Response

200 (OK)
Content-Type: application/json
{"response":{"type":"status","body":{"jobid":"12345","description":"Job launched using Quick Launch","profile":"Default-Profile","status":"completed","progress":"100"}}}

GET

/api/query/{token}/jobs/{profileName}

Get a list of every job a user has ever run. The optional profileName parameter allows users to filter the results to just jobs launched using that profile

Response

200 (OK)
Content-Type: application/json
{"response":{"type":"status","body":{"jobid":"12345","description":"Job launched using Quick Launch","profile":"Default-Profile","status":"completed","progress":"100"}}}

XLATE

“xlate” allows users to retrieve a translation from their API instance, assuming that they have successfully started it beforehand. The translations returned will be determined by the particular client profile that they launched the API with. The “xlate” command supports so-called “chunking” whereby multiple source segments can be bundled into a single request and processed, then returned in bulk to reduce the network overhead incurred if the user were to perform individual requests for each segment. The “xlate” request can be performed using either HTTP GET or HTTP POST requests.

HTTP GET is appropriate if the user is sending relatively small (i.e. < 50) segment volumes per request, if the client application is not capable of performing HTTP POST requests or if the user does not need to use segment ids. The API expects “xlate” GET requests to pass segments as URL-encoded URL parameters.

However, different URL length limitations are often applied to GET requests depending on the client application making the request, and/or the server processing it. A URL length of 2000 bytes or less is advisable using the GET method. For further information, consult the documentation for the programming language or operating system that the client software is implemented with.

HTTP POST is appropriate if the user wishes to send arbitrarily large segment volumes or if they want to attach ids to each segment.

GET

/api/xlate/{token}/{profileName}/this is a segment/so is this/and this one too

Submit segments to be translated(“this”, “is”, “a”, “string”) for translation to the API via HTTP GET, for the user account associated with token using the client profile profile, and return translations inside a JSON array. The start of each segment in the request is delimited by a forward slash and the first segment occurs in the URL after the slash that follows the profile name. Segments containing forward slashes should double URL-encode the forward slash to the value %%252F to stop the slash being interpreted as a URL parameter.

Response

200 (OK)
{"response":{"type":"translation","body":{"translationData":[{"src":"this","trg":"cette","id":""},{"src":"is","trg":"est","id":""},{"src":"a","trg":"un","id":""},{"src":"string","trg":"string","id":""}]}}}

POST

/api/xlate

Perform a HTTP POST containing segments to be translated, and the id of the segments. Required parameters in the POST body are authwhich is the authorisation token, profile which is the profile you wish to use to translate the segment, and then 1 or more segments, with their parameter names serving as the segment ids. Segments containing ampersand characters in their content should be double URL-encoded to the value %2526 to prevent the ampersand being interpreted as a URL parameter.

Response

200 (OK)
Content-Type: application/json
{"response":{"type":"translation","body":{"translationData":[{"src":"Hello","trg":"Bonjour","id":1}]}}}

SHUTDOWN

The shutdown command terminates a running API instance. The command is issued as a HTTP GET request with two parameters which are the access token provided by KantanMT, and the name of the client profile whose API instance you want to shut down. Upon completion of the request, the API returns a JSON message indicating that the termination process has begun, or that the API is already offline if it is. As with the “init” command, shutdown can take several minutes to complete, so client applications should send the shutdown command, and periodically poll the API using the “query” command to determine when shutdown completes.

GET

/api/shutdown/{token}/{profileName}

Shuts down the API instance associated with the user account that uses the access token token and hosts the client profile profileName

Response

200 (OK)
Content-Type: application/json
{"response":{"type":"status","body":{"state":"terminating"}}}

UPLOADCD

uploadcd allows users to add translatable files to the “client files” folder for a given client profile.

The API restricts uploaded files to a 2 megabyte maximum and 1 byte minimum size, and the files must be one of the accepted file types listed here. Uploading a file with the same name as a file that already exists in the “client files” folder will overwrite the old file.

The API also allows users to translate remotely stored files by uploading a file ending in the .lnk extension, containing URLs to the translatable files. When you run a translation job, the KantanMT backend will download those files and translate them, with the translated files appearing in your results.zip file. The downloaded source files specified in the .lnk files do not appear or persist in your client files after the translation job completes, but the .lnk file does along with any other client files you had already. The format for each line of a .lnk (link File) is as follows:

--user=userName --password=passWord qualified_url

Parameters:

  • --user=userName : Your FTP/HTTP username (if needed)
  • --password=passWord : Your HTTP/FTP password (if needed)
  • qualified_url : Fully expanded URL for file to be translated.

All files must be uploaded as part of a HTTP multi-part POST request in line with the W3C HTTP specifications. A multi-part POST is a request which contains a mixture of parameter types, including strings, file contents etc. There are several libraries like HttpClient for Java which support the execution of multi-part requests, and their documentation should be consulted for further information. The API expects three parameters - the authorisation token of a user account, the name of the client profile that the file will be uploaded to, and the file itself. There is also a fourth, optional parameter called "folder" which allows users to upload translatable files to a named "folder" which resides outside of the usual client data folder. When you wish to translate these files, you should include the name of this folder as a parameter in the "launchjob" command described further below in this document, and the job will translate the files in the named folder, instead of the default "client data" belonging to the client profile you have used to launch the job with. It is recommended that you use this parameter if you wish to use the same client profile in two simultaneous translation jobs that translate different sets of files.

POST

/api/uploadcd

Upload a file called "test.txt" to the client data folder of the profile called Default-Profile associated with the user account that owns the token auth with a value of 123456789

Response

200 (OK)
Content-Type: application/json
{"response":{"type":"status","body":{"state":"file uploaded successfully","profile":"Default-Profile"}}}

UPLOADTD

uploadtd allows users to add training data to the "training data" folder for a given client profile

The API restricts uploaded files to a 2 megabyte maximum and 1 byte minimum size. Uploading a file with the same name as a file that already exists in the "training data” folder will overwrite the old file.

All files must be uploaded as part of a HTTP multi-part POST request in line with the W3C HTTP specifications. A multi-part POST is a request which contains a mixture of parameter types, including strings, file contents etc. There are several libraries like HttpClient for Java which support the execution of multi-part requests, and their documentation should be consulted for further information. The API expects three parameters - the authorisation token of a user account, the name of the client profile that the file will be uploaded to, and the file itself.

POST

/api/uploadtd

Upload a file called "training.tmx" to the client data folder of the profile called Default-Profile associated with the user account that owns the token auth with a value of 123456789

Response

200 (OK)
Content-Type: application/json
{"response":{"type":"status","body":{"state":"file uploaded successfully","profile":"Default-Profile"}}}

LAUNCHJOB

The launchjob command allows users to launch a translation job via the API using a specified client-profile. This is equivalent to pressing “Translate!” on the user dashboard on the KantanMT website. The API limits users to 2 running jobs at a time. Users can invoke the launchjob command using either HTTP GET or POST requests. For both request types, the API expects a user authorisation token and client profile name as parameters. There is a third, optional parameter which is a named upload location that was used as part of the "uploadcd" command described above. Using this parameter will result in the translation job translating the files in this folder, instead of the default "client data" folder belonging to the profile used to launch the job.

GET

/api/launchjob/{token}/{ProfileName}(/folder)

Launch a translation job using using profileName as the profile to translate with.

Response

200 (OK)
Content-Type: application/json
{"response":{"type":"status","body":{"state":"translation job launched successfully","profile":"Default-Profile","jobid":"18199"}}}

LAUNCHBUILD

The launchbuild command allows users to launch a build job via the API using a specified client-profile. This is equivalent to pressing “Build!” on the user dashboard on the KantanMT website. The API limits users to 2 running jobs at a time. Users can invoke the launchbuild command using either HTTP GET or POST requests. For both request types, the API expects a user authorisation token and client profile name as parameters.

GET

/api/launchbuild/{token}/{ProfileName}

Launch a translation job using using profileName as the profile to translate with.

Response

200 (OK)
Content-Type: application/json
{"response":{"type":"status","body":{"state":"build job launched successfully","profile":"Default-Profile","jobid":"18199"}}}

RETRAIN

The retrain command allows users to use the KantanISR Instant Segment Retraining feature. This feature takes training data in the form of a source/translated segment pair and incorporates it an existing client profile, without having to rebuild that profile. When the user sends a subsequent translation request to the API using the "retrained" client profile, it will use the "retraining" data they submitted previously as part of the translation process.

Users can invoke the retrain command using HTTP GET requests. The API expects a user authorisation token, client profile name, a source segment, and its translation, in the languages the user specified at profile creation time.

GET

/api/retrain/{token}/{ProfileName}/{source}/{target}

Launch a translation job using using profileName as the profile to translate with.

Response

200 (OK)
Content-Type: application/json
 {"response":{"type":"status","body":{"state":"retraining data uploaded successfully","profile":"ProfileName"}}}

GETRESULTS

The getresults command allows users to download the translated files from a previously run translation job. Users simply supply their authentication token and the job id of the translation job they want to retrieve files from, and the API will respond with a file called "results.zip", containing all of the translated files that were produced for that job. If the user supplies an invalid job id or an id for a non-translation job such as a build or analytics job, the API will return a JSON error message.

Users can invoke the GETRESULTS command using HTTP GET requests. The API expects a user authorisation token and a valid job id.

GET

/api/getresults/{token}/{jobid}

Launch a translation job using using profileName as the profile to translate with.

Response

200 (OK)
Cache-Control: public
Cache-control: no-cache="set-cookie"
Content-Description: File Transfer
Content-Disposition: attachment; filename="results.zip"
Content-Transfer-Encoding: binary
Content-Type: application/octet-stream
Date: Wed, 13 Nov 2013 11:43:06 GMT
Expires: 0
Pragma: public
Server: Apache/2.2.22 (Ubuntu)
Set-Cookie: AWSELB=D91F4B01042813BC1E70DFB850AD6C8C0BCF70E395C3A4E2AEBB656D014A94FCB90C07EA5E7009088AB46488CBCF185896BA9AA67FEDE6ABC609C08AEE5E1F7D45CA71348B;PATH=/;MAX-AGE=1500
X-Powered-By: PHP/5.3.10-1ubuntu3.6
Content-Length: 125912
Connection: keep-alive

Response

401 (Unauthorized)
Content-Type: application/json
 {"response":{"type":"error","body":"unknown job id"}}