TAUS Translation API Specification

#TAUS Translation API – Version 2.0

##TAUS Technical Specification - A Common Translation Services API

July 2014

Authors

Klemens Waldhör, TAUS

TAUS Review Team

Achim Ruopp, TAUS
Chase Tingley, Spartan Software
Vinod Sudharshan, TAUS

Reviewed and commented by

Rahzeb Choudhury, TAUS
Sanjay Bhansali, Vladimir Weinstein, Google
Gustavo Lucardi, Trusted Translations
Grant Straker, Straker Translations
Hans Timmerman, AVB Vertalingen
Marco Trombetti, Translated.net
Jörg Schütz, bioloom group
Alan Melby, Linport project

Initial Author
Brian McConnell, Gengo

Document Version

1.1 from 20.09.2012
1.2 from 23.01.2013
2.0h from 20.08.2014

This work is licensed under the Creative Commons Attribution 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by/4.0/ or send a letter to Creative Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA.

For further information, please email [email protected]

##Overview TAUS Translation API translation request v2.0 methods

The following table describes the basic requests supported by API Version 2.0. An overview of the requests methods of API version 1.4 is given at the end of the paper.

Request Method	Function / HTTP Verbs	Typical Use Cases	Required
translation	Get, submit, change, delete translations	This is the core method of the API and processes translations.	Yes
	GET	Get a translation request based on an <id> or filter criteria
	POST	Create a new translation request
	PUT	Change a translation request. Esp. the following methods are supported:accept, reject, confirm, cancel
	DELETE	Remove a translation request
comment	View and submit comments about translations	Crowd translation services, professional translation services that allow user feedback, comments or discussion.	No
	GET	Get a comment request based on an <id> or some filter criteria
	POST	Create a new comment request
	PUT	Change a comment request
	DELETE	Remove a comment request
score	View and submit scores for translations	Crowd and professional translation services that allow user feedback and/or professional translator QA services, as well as moderated crowd translation systems.	No
	GET	Get a score request based on an <id> or filter criteria
	POST	Create a new score request
	PUT	Change a score request
	DELETE	Remove a score request
callback	Run a callback function	Call a function at requester side when changes happen on server side	No
	POST	Send request changes using a call back URL
All methods	Get request attribute values	This allows retrieving specific attributes and their values
{request-method}/{attribute}/{id}	GET	Return the value of a specified attribute for a request method above.	No

##RESTful Web services

The methods of the API (HTTP verbs; RFC 2616 are based on the CRUD principle:

Operation	HTTP Method	Comment
C REATE	POST	All methods which create a new request on the server
R EAD	GET	All methods which return a request or other information; does not change anything on the server side
U PDATE	PUT	All methods which change a given request. Formally a PUT requires to submit the whole resource again.
	PATCH	All methods which change a subset of the attributes of given request
D ELETE	DELETE	All methods which remove requests

All method parameters are passed either as MIME types JSON (application/json) or XML (application/xml, text/xml). The following shows a JSON formatted example translation request:

{ "translationRequest":
    {
        "id": "2b575fdc-f6af-4b9e-850d-9dc0884c6595",  
        "sourceLanguage":"de-DE",  
        "targetLanguage": "en-US",  
        "source": "Diesen Text übersetzen",
        "mt": true,
        "professional": false,
        "creationDatetime": "2014-07-12T23:57:02Z",
        "updateCounter": 0
    }
}

The following shows the same example translation request as XML:

<translationRequest>
<id>2b575fdc-f6af-4b9e-850d-9dc0884c6595</id>
    <sourceLanguage>de-DE</sourceLanguage>
    <targetLanguage>en-US\</targetLanguage>
    <source>Diesen Text übersetzen</source>
    <mt>true</mt>
    <professional>false</professional>
    <creationDatetime>2014-07-12T23:57:02Z</creationDatetime>
    <updateCounter>0</updateCounter>
</translationRequest>

##Request Definition and Structure

###Request IDs

Each request has a unique id {id} associated with it. Unique ids have to be generated by the originator (requester) of the request. Request ids follow the GUID-format (Globally Unique Identifier). Example: 2b575fdc-f6af-4b9e-850d-9dc0884c6595. GUIDs can be easily generated by various programming languages. Request IDs should not be changed by applications working with the request once the GUID has been generated.

###Attribute Naming

Attribute naming follows the Google JSON Style Guide. The naming scheme is forwarded to XML element names.

###Attribute values

Attribute values are in general any legal JSON attribute value or XML content. The legal values are given with attributes. If a request does not specify a value, null is assumed. Empty string and null are different values. The comparison null=="" will return false. Null is also returned if an attribute is queried which was not set for the request. In case default values are specified, the default value will be used. Default values are given in bold. YES and NO are represented using the JSON Boolean values true and false.

###Language Codes

Several requests require specifying a language code. Language codes should be based on BCP47 conventions. Examples are: de for German, de-DE for German for Germany, sr-Cyrl for Serbian written using the Cyrillic script.

###Handling requests and parameter with conflicting requirements

If conflicts occur between parameter values specified in the request and values specified in the payload of a request the application has to return an HTTP error code 409 (Conflict in resource) together with an error object. A payload is defined here as any part of the request (attribute – value pairs) or files attached to the request. A typical payload could be represented by an XLIFF file or a TIPP package.

Example: Different values in the request for source language and the language specified in a XLIFF file.

###Using files and URLs

Depending on the type of translation required clients can optionally submit documents as files or URL references. This is an alternative instead of sending the texts in the source and target field of a translation request.

In this specification Request Body describes the structure of the request body if required. If a “*“ is used for content type, the “*” needs to be replaced with the correct MIME type (for example application/xml or similar). Request Body only describes HTTP header attributes relevant to this specification, not all required parts for a HTTP request (like content-length and so on).

The type [multipart/form-data](http://www.ietf.org/rfc/rfc2388.txt) should be used for POST,PUT and GET for file transfers and URL references. Multipart forms require that each part of the multipart message is divided by boundary string (defined in section 4.1 of the multipart/form-data description. "As with other multipart types, a boundary is selected that does not occur in any of the data."). In the examples below aboundarystring is used to separate the different parts of the message.

###File Handling

The following naming schemes must be applied if files are used:

Names for files (attached) are sourceDocument and/or targetDocument.

Content Type: multipart/form-data; boundary=aboundarystring

--aboundarystring

Content Type: application/json: name="translationRequest"

translation request

--aboundarystring

Content Type: *;name="sourceDocument"

source document

--aboundarystring

Content Type: *;name="targetDocument"

target document

--aboundarystring

URL Handling

In many cases documents, more general any kind of payloads cannot be sent as part of the message (e.g. because of the size of the document). In this case URLs representing a resource can be used instead. URLs can be used to reference resources on the web which should be used as part of the translation process. The service is then responsible for retrieving these resources. If URLs are used the following content type should be used in the multipart message:

Content-type: message/external-body; access-type=URL;
    URL=http://www.foo.com/file

Thus requires adding some information if source or target is referenced by the URL:

Content-type: message/external-body; access-type=URL;
    URL=”http://www.taus.net/upload/myfileen.docx”;
    type=”sourceDocument”;

Content-type: message/external-body; access-type=URL;
    URL=”http://www.taus.net/upload/myfileen.docx”;
    type=”targetDocument”;

or using ftp:

Content-type: message/external-body; access-type=URL;
    URL=”ftp://www.taus.net/upload/myfileen.docx”;
    type=”targetDocument”;

Content-type: message/external-body;
    access-type=ANON-FTP;
    site="ftp.taus.org";
    mode="binary";
    directory="/pub/documentation"; name="myfileen.docx";
    type=”targetDocument”;

###Workflow handling, links and callbacks in requests

####Linking requests

RESTful Web APIs should inform the client which operations (requests) are allowed based on a resource. This is known as the HATEOAS – Hypermedia as the Engine of Application State – principle. This requires defining a link element (similar to the <a> element in html). The link attribute should contain all necessary information for the client to run a follow-up request. Unfortunately there is no real standard out there describing such a link for different formats.

One option are links as defined by the W3C consortium (http://www.w3.org/TR/html401/struct/links.html) which we will follow for this specification.

Each request can contain a list of link for the possible next operations.

A link contains the following attributes:

Attribute	Value	Comment
type	Content type	The content type for the request
href	URI	The URI for the request
verb	http verb	GET, POST, PUT, PATCH, DELETE
title	string	A string describing the request; this is mainly targeted to human readers helping to understand the possible requests. This is optional.
rel	string	The rel attribute specifies the relationship between the current document and the linked document. The following relationships are currently supported: translation, comment, score

Links can be used in JSON or XML. The following explains the format.

#####JSON Formatted Translation Request

{ "links":
    [ {
	type: <allowed mediatype>,
	href: <uri>,
	verb: <a http verb>,
	title: <string>,
	rel: <rel type string>
    }, … ]
}

Example:

{"translationRequest": {
    "id": "2b575fdc-f6af-4b9e-850d-9dc0884c6595",

    …

    "links": [
    { 
	"rel": "translation",
	"href": "http://www.example.com/translationRequests/2b575fdc-f6af-4b9e-850d-9dc0884c6595",
	"type": "application/json",
	"title": "Newly created translation request 2b575fdc-f6af-4b9e-850d-9dc0884c6595 created on 7/23/2014",
	"verb": "GET"
    },
    {
	"rel": "translation.cancel",
	"href": "http://www.example.com/translationRequests/cancel/2b575fdc-f6af-4b9e-850d-9dc0884c6595",
	"type": "application/json",
	"verb": "PUT"
    },
    {
	"rel": "comment", 
	"href": "http://www.example.com/translationRequests/2b575fdc-f6af-4b9e-850d-9dc0884c6595",
	"type": "application/json",
	"verb": "POST"

    },
    ]
    }

}

#####XML Formatted Translation Request

<links>
    <link>
	<type><!-- content type --></type>
	<href><!-- uri --></href>
	<verb><!-- allowed http words --></verb>
	<title><!-- description string --></title>
	<rel><!-- rel type string --</title>
    <link>
</links>

Example:

<links>
    <link>
	<type>application/json</type>
	<href>http://www.example.com/translationRequests/2b575fdc-f6af-4b9e-850d-9dc0884c6595</href>
	<verb>GET</verb>
	<title>Newly created translation request 2b575fdc-f6af-4b9e-850d-9dc0884c6595 created on 7/23/2014</title>
	<rel>translation</rel>
    <link>
    ...
</links>

###Call Back URLs

Requests support the specification of a callback URL, which is an alternative to status polling. This URL will used by the receiver of the request to inform the requester about the progress of the request. As there are no real standards out there several formats could be used. Here are some examples formats:

URLs following the x-callback-url specification
Web hooks: URLs which can be called by the server (e.g. using a HTTP POST message). There is no real standard definition out there. So it is up to the implementation what these links looks like.

A callback is implemented as a service on the respective side (e.g. client). If a server calls a callback it sends a CALLBACK POST request to the requester of the message. The body of the CALLBACK method contains the attributes of the original request, a comment field and callbackStatus field describing the changes, actions etc. applied by the server.

##Translation request

A translation request can either be represented as JSON formatted string or XML formatted and it can be either used for submitting a new or changed request or as return result. Attributes in italic are optional. Bold attributes are generated by the POST or PUT request on the server. The name to be used for embedding this request is: translationRequest

Attribute	Value	Comment
id	<id>	Translation request id generated when a new request is created (POST) or used when a request should be changed (PUT). The requester creates the id.
callbackURL	call back url	An URL which will be used by the receiver to inform the requester about the progress of the request.
sourceLanguage	<source language code>	Can be omitted if application determines language or part of the payload
links	A link description	This follows the format described in “workflow handling and links in requests”. At least one link should present for each request
targetLanguage	<target language code>	Can be omitted if application determines language or part of the payload
source	<source text>	Can be omitted if text is part of the payload (file, URL …). Text is interpreted as plain text.
target	<target text>	Can be omitted if text is part of the payload (file, URL …). Text is interpreted as plain text.
mt	<true/false>	Machine translation yes / no
crowd	<true/false>	Crowd translation required yes / no
professional	<true/false>	Professional translation required yes / no
postedit	<true/false>	Post editing of translation required yes / no; this is important if the original translation is based on a MT translation or TM match
comment	<string>	Any comment
translator	<string>	Translator of target
owner	<string>	Owner of request
creationDatetime	ISO 8601 formatted string	Date and time of request; generated when request is created
modificationDatetime	ISO 8601 formatted string	Date and time of request; generated when request is modified
updateCounter	<int>	Number of changes applied to request
status	<string>	Status of request. Allowed values are: initial, translated, reviewed, final, rejected, accepted, pending, timeout; initial: state when the request is created; translated: request has been translated; reviewed: The translation has been reviewed by a reviewer; final: translation is now finally finished and can be used for production; rejected: The request as such was rejected, e.g. by a translation provided or the translation was rejected (e.g. because of quality) by the client; accepted: the request was accepted by the translation provider or the translation was accepted by the client; pending: The request is in some client or service provider internal process (e.g. approval); timeout: the request status has not changed for a long time; Default value upon creation: initial

If source and/or target are empty source and target documents can be submitted as part of a multipart/form-data message with name: sourceDocument and/or: targetDocument.

###JSON Formatted Translation Request

{ "translationRequest":
    {
	"id":<string>,
	any attribute from the above definition
	"status":<string>
    }
}

###XML Formatted Translation Request

<translationRequest>
    <id>string content</id>
    <!-- any attribute from the above definition -->
    <status>string content</status>
</translationRequest>

##Comment request

The name to be used for embedding this request is: commentRequest

Attribute	Value	Comment
id	<id>	Comment request id generated when a new request is created (POST) or used when request should be changed (PUT).
referenceId	<requestid>	Id of the request the comment references; it can be a translation, comment or score request
callbackURL	call back url	An URL which will used by the receiver to inform the requester about the progress of the request.
links	A link description	This follows the format described in “workflow handling and links in requests”. At least one link should present for each request
language	<language code>	Language of comment
text	<string>	Comment text; format is a plain text string; no formatting information (html) should be used.
*creationDatetime *	ISO 8601 formatted string	Date and time of request; generated when request is created

###JSON Formatted Comment Request

{ "commentRequest":
    {
	"id":<string>,
	any attribute from the above definition
	"text":<string>
    }
}

###XML Formatted Comment Request

<commentRequest>
    <id>string content</id>
    <!-- any attribute from the above definition -->
    <text>string content</text>
</commentRequest>

##Score request

The name to be used for embedding this request is: scoreRequest

Attribute	Value	Comment
id	<id>	Score request id generated when a new request is created (POST) or used when request should be changed (PUT).
requestId	<translation-requestid>	Id of the translation request for the score
callbackURL	call back url	An URL which will used by the receiver to inform the requester about the progress of the request.
links	A link description	This follows the format described in “workflow handling and links in requests”. At least one link should present for each request
score	<float> (0.0 -100.0)	Score value; the allowed value is between 0.0 and 100.0. Format of the number given as a regular expression: dd?d?\.d
crowd	<true/false>	Crowd translation required yes / no
professional	<true/false>	Professional translation required yes / no
text	<string>	Score comment text
*creationDatetime *	ISO 8601 formatted string	Date and time of request; generated when request is created

###JSON Formatted Score Request

{ "scoreRequest":
    {
	"id":<string>,
	any attribute from the above definition
	"score":<string>
    }
}

###XML Formatted Score Request

<scoreRequest>
    <id>string content</id>
    <!-- any attribute from the above definition -->
    <score>number content</score>
</scoreRequest>

##Callback request

The name to be used for embedding this request is: callbackRequest

Attribute	Value	Comment
id	<id>	Callback request id generated when a new request is created (POST) or used when request should be changed (PUT).
requestId	<requestid>	Id of the request the callback references; it can be a translation, comment or score request
links	A link description	This follows the format described in “workflow handling and links in requests”. At least one link should present for each request
callbackText	<string>	Textual information about the changes done by the server
callbackStatus	<string>	Status information about the changes done by the server
callBackcreationDatetime	ISO 8601 formatted string	Date and time of callback request; generated when request is created
attributes...	<attributes of the origin request>	This is a copy of the attributes of the original request; the id of the original request must be removed and goes into the requestId attribute. Any file or URL attachments are not copied.

JSON Formatted Callback Request

{ "callbackRequest":
    {
	"id":<string>,
	any attribute from the above definition
	"callbackText":<string>
    }
}

XML Formatted Callback Request

<callbackRequest>
    <id>string content</id>
    <!-- any attribute from the above definition -->
    <callbackStatus>number content</callbackStatus>
</callbackRequest>

##Error Response

Errors are signaled using standard HTTP codes. If more specific error messages are needed, an error JSON object should be returned.

###Important HTTP Status Codes

HTTP Status Code	Description
200	Request id found
201	A new resource was created
400	Bad Request
401	Authentication Error/Access Denied
404	Request id not found
405	Method not allowed
409	Conflict in resource
415	Media Type or Output Format Not Supported
422	Semantic error in request
500	Server Failure
501	Service/Method not implemented

###Error Response Object

The API defines some basic error attributes which a method should return if an error occurs, esp. for http status code >= 400. The name to be used for embedding this request is: error

Attribute	Value	Comment
id\<id>	Error request id; each error request has its specific id so that it can later be referenced
requestId	<translation-requestid>	Id of the request which generated the error
errorMessage	<string>	Human readable error message
httpCode	<int>	The http status code returned by the method
datetime	ISO 8601 formatted string	Date and time of error; generated when error request is created
userMessage	<string>	A message for the end user
developerMessage	<string>	A message for the developer
errorCode	<int>	An application specific error code
…	<string>	More attributes generated by the server (e.g. stack traces). The naming scheme is up to the implementation.

####JSON Formatted Error Response

{ "error":
    {
	"id":<string>,
	any attribute from the above definition
	"errorMessage":<string>
    }
}

####XML Formatted Error Response

<error>
    <id>string content</id>
    <!-- any attribute from the above definition -->
    <errorMessage>number content</errorMessage>
</error>

Return Content Type

If a method returns an object (e.g. a resource) it can be either application/json, application/xml or text/xml. If it contains files etc. it should be multipart/form-data.

##TAUS API Requests

###API Versioning

In order to support and different versions of the TAUS Restful API a version number is added as part of the URL of the request. The current version number is 2.0. The URL starts with the server URL followed by the version followed by the request method.

Format is: <server>/<version>/<request method>

An API request could then be called like this:

www.example.com/**v2.0**/translationRequests/2b575fdc-f6af-4b9e-850d-9dc0884c6595

Older version (1.2) can be called like that:

www.example.com/**v1.2**/translation/get?session=123456&content-type=text&group-name=&st=Text&tt=Text&language=All&sl=de&tl=en&mt=y&crowd=y&professional=r

###TRANSLATION Request

GET Methods

#####URL translation

#####Method GET

#####Request Body application/json, application/xml, text/xml

#####Returns

HTTP Status Code	Description
200	Request ids found
401	Authentication Error/Access Denied
415	Media Type or Output Format Not Supported
422	Semantic error in request
500	Server Failure
501	Service/Method not implemented

#####Comment Returns JSON or XML links as described in “workflow handling and links” with all translation request available. The request body may contain attributes which filter the requests to be returned, e.g. by specifying sourceLanguage “de-de” which would return only those request ids of sourceLanguage “de-de”. A request body could look like this:

<translationRequest>
     <sourceLanguage>de-DE<sourceLanguage>
     <mt>true</mt>
</translationRequest>

Or as JSON

{ "translationRequest":
    {
	"sourceLanguage":"de-DE",
	"mt":true
    }
}

This would return all requests with source language de-DE and mt set to true. A regular expression can be used for the value. If no requests are found an empty link list is returned. In order to support web browser like URLs an example URL with a filter may could also look like this.

translation?sourceLanguage=de-de&targetLanguage=en-us

#####URL translation/{id}

#####Method GET

#####Request Body application/json, application/xml, text/xml

#####Returns

HTTP Status Code	Description
200	Request id found
401	Authentication Error/Access Denied
404	Request id not found
415	Media Type or Output Format Not Supported
422	Semantic error in request
500	Server Failure
501	Service/Method not implemented

#####Comment Returns the translation request with id {id}. Depending on the request the return content type could be multipart/form-data.

#####URL status/{id}

#####Method GET

#####Request Body application/json, application/xml, text/xml

#####Returns

HTTP Status Code	Description
200	Request id found
401	Authentication Error/Access Denied
404	Request id not found
415	Media Type or Output Format Not Supported
500	Server Failure
501	Service/Method not implemented

#####Comment Returns the status of translation request with id {id}

POST

#####URL translation

#####Method POST

#####Request Body No files: application/json, application/xml, text/xml With files:

Content Type: multipart/form-data; boundary=aboundarystring
--aboundarystring
Content Type: application/json: name="translationRequest"
*translation request*
--aboundarystring
Content Type: application/\*;name="sourcedocument"
*source document*
--aboundarystring
Content Type: application/\*;name="targetdocument"
*target document*
--aboundarystring

#####Returns

HTTP Status Code	Description
201	Translation request successfully created
401	Authentication Error/Access Denied
415	Media Type or Output Format Not Supported
500	Server Failure
501	Service/Method not implemented

#####Comment Creates the translation request with id {id}; the request body contains the translation request content. One can submit a source document alone or both source and target documents. For using URLs see discussion in chapter about links and URLs.

PUT

#####URL translation/{id}

#####Method PUT

#####Request Body No files: application/json, application/xml, text/xml

With files:

Content Type: multipart/form-data; boundary=aboundarystring
--aboundarystring
Content Type: application/json: name="translationRequest"
translation request
--aboundarystring
Content Type: application/\*;name="sourcedocument"
source document
--aboundarystring
Content Type: application/\*;name="targetdocument"
target document
--aboundarystring

Returns

According to RFC 2616 section 9.6: If a new resource is created, the origin server MUST inform the user agent via the 201 (Created) response. If an existing resource is modified, either the 200 (OK) or 204 (No Content) response codes SHOULD be sent to indicate successful completion of the request.

HTTP Status Code	Description
200	Translation request successfully changed
401	Authentication Error/Access Denied
404	Request id not found
415	Media Type or Output Format Not Supported
500	Server Failure
501	Service/Method not implemented

#####Comment Changes the translation request with id {id}; the request body contains the translation request content with the required changes

If request with id {id} does not exist 404 has to be returned. It is ok just to submit just a source or a target document.

See also chapter about PATCH method for changing single or few attributes.

#####URL accept/{id} #####Method PUT

#####Request Body application/json, application/xml, text/xml

#####Returns

HTTP Status Code	Description
200	Translation request successfully changed
401	Authentication Error/Access Denied
404	Request id not found
415	Media Type or Output Format Not Supported
500	Server Failure
501	Service/Method not implemented

#####Comment Accepts the translation request with id {id} and changes the state (status) of the request to “accepted“.

#####URL reject/{id}

#####Method PUT

#####Request Body application/json, application/xml, text/xml

#####Returns

HTTP Status Code	Description
200	Translation request successfully rejected
401	Authentication Error/Access Denied
404	Request id not found
415	Media Type or Output Format Not Supported
500	Server Failure
501	Service/Method not implemented

#####Comment Rejects the translation request with id {id} and changes the state (status) of the request to rejected

#####URL confirm/{id}

#####Method PUT

#####Request Body application/json, application/xml, text/xml

#####Returns

HTTP Status Code	Description
200	Translation request successfully changed
401	Authentication Error/Access Denied
404	Request id not found
415	Media Type or Output Format Not Supported
500	Server Failure
501	Service/Method not implemented

#####Comment Confirms the translation request with id {id} and changes the state (status) of the request to confirmed

URL

cancel/{id} #####Method PUT

#####Request Body application/json, application/xml, text/xml

#####Returns

HTTP Status Code	Description
200	Translation request successfully changed
401	Authentication Error/Access Denied
404	Request id not found
415	Media Type or Output Format Not Supported
500	Server Failure
501	Service/Method not implemented

#####Comment Cancel the translation request with id {id}; and changes the state (status) of the request to “cancelled“. NOTE: The API uses PUT instead of DELETE as deleting the request may be a follow up operation.

PATCH

#####URL translation/{id}

#####Method PATCH

#####Request Body No files: application/json, application/xml, text/xml

With files:

Content Type: multipart/form-data; boundary=aboundarystring
--aboundarystring
Content Type: application/json: name="translationRequest"
translation request
--aboundarystring
Content Type: application/\*;name="sourcedocument"
source document
--aboundarystring
Content Type: application/\*;name="targetdocument"
target document
--aboundarystring

#####Returns

HTTP Status Code	Description
200	Translation request successfully changed
401	Authentication Error/Access Denied
404	Request id not found
415	Media Type or Output Format Not Supported
500	Server Failure
501	Service/Method not implemented

#####Comment Changes the translation request with id {id}; the request body contains the translation request content with the required changes If request with id {id} does not exist 404 has to be returned. It is ok just to submit just a source or a target document. Difference to PUT: The semantics of PUT requires submitting the whole changed resource again, which might be very inefficient, esp. when containing huge files. PATCH could be used instead when only few attributes need to be changed.

####DELETE

#####URL translation/{id}

#####Method DELETE

#####Request Body application/json, application/xml, text/xml

#####Returns

HTTP Status Code	Description
204	No content (successfully deleted)
401	Authentication Error/Access Denied
404	Request id not found
415	Media Type or Output Format Not Supported
500	Server Failure
501	Service/Method not implemented

#####Comment Deletes the translation request with id {id}; the request body contains the translation request id

###COMMENT related Methods

####GET

#####URL comment

#####Method GET

#####Request Body application/json, application/xml, text/xml

#####Returns

HTTP Status Code	Description
200	Request id found
401	Authentication Error/Access Denied
404	Request id not found
415	Media Type or Output Format Not Supported
422	Semantic error in request
500	Server Failure
501	Service/Method not implemented

#####Comment Returns JSON or XML links with all comment requests. The request body may contain attributes which filter the requests to be returned.

#####URL comment/{id}

#####Method GET

#####Request Body application/json, application/xml, text/xml

#####Returns

HTTP Status Code	Description
200	Comment id found
401	Authentication Error/Access Denied
404	Request id not found
415	Media Type or Output Format Not Supported
500	Server Failure
501	Service/Method not implemented

#####Comment Returns the comment request with id {id}

####POST

#####URL comment

#####Method POST

#####Request Body application/json, application/xml, text/xml

#####Returns

HTTP Status Code	Description
201	Comment request successfully created
401	Authentication Error/Access Denied
415	Media Type or Output Format Not Supported
500	Server Failure
501	Service/Method not implemented

#####Comment Creates the a comment for request with id {id}; the request body contains the comment content.

####PUT

#####URL comment/{id}

#####Method PUT

#####Request Body application/json, application/xml, text/xml

#####Returns

HTTP Status Code	Description
200	Comment request successfully changed
401	Authentication Error/Access Denied
404	Request id not found
415	Media Type or Output Format Not Supported
500	Server Failure
501	Service/Method not implemented

#####Comment Changes the comment with id {id}; the request body contains the translation request content with the required changes

####PATCH

#####URL comment /{id}

#####Method PATCH

#####Request Body application/json, application/xml, text/xml

#####Returns

HTTP Status Code	Description
200	Comment request successfully changed
401	Authentication Error/Access Denied
404	Request id not found
415	Media Type or Output Format Not Supported
500	Server Failure
501	Service/Method not implemented

#####Comment Changes the comment request with id {id}; the request body contains the comment request content with the required changes If request with id {id} does not exist 404 has to be returned.

####DELETE

#####URL comment/{id}

#####Method DELETE

#####Request Body application/json, application/xml, text/xml

#####Returns

HTTP Status Code	Description
204	No content (successfully deleted)
401	Authentication Error/Access Denied
404	Request id not found
415	Media Type or Output Format Not Supported
500	Server Failure
501	Service/Method not implemented

#####Comment Deletes the comment with id {id}; the request body contains the request id. If request does not exist 404 has to be returned.

###SCORE related Methods

####GET

#####URL score

#####Method GET

#####Request Body application/json, application/xml, text/xml

#####Returns

HTTP Status Code	Description
200	Request id found
401	Authentication Error/Access Denied
404	Request id not found
415	Media Type or Output Format Not Supported
422	Semantic error in request
500	Server Failure
501	Service/Method not implemented

#####Comment Returns JSON or xml links with all score request. The request body may contain attributes which filter the requests to be returned.

#####URL score/{id}

#####Method GET

#####Request Body application/json, application/xml, text/xml

#####Returns

HTTP Status Code	Description
200	Score id found
401	Authentication Error/Access Denied
404	Request id not found
415	Media Type or Output Format Not Supported
500	Server Failure
501	Service/Method not implemented

#####Comment Returns a score request with id {id}.

####POST

#####URL score

#####Method POST

#####Request Body application/json, application/xml, text/xml

#####Returns

HTTP Status Code	Description
201	Comment request successfully created
401	Authentication Error/Access Denied
415	Media Type or Output Format Not Supported
500	Server Failure
501	Service/Method not implemented

#####Comment Creates a score request for request with id {id}; the request body contains the score content

####PUT

#####URL score/{id}

#####Method PUT

#####Request Body application/json, application/xml, text/xml

#####Returns

HTTP Status Code	Description
200	Score request successfully changed
401	Authentication Error/Access Denied
404	Request id not found
415	Media Type or Output Format Not Supported
500	Server Failure
501	Service/Method not implemented

#####Comment Changes the score request with id {id}; the request body contains the translation request content with the required changes; if request does not exist 404 has to be returned.

####PATCH

#####URL score/{id}

#####Method PATCH

#####Request Body application/json, application/xml, text/xml

#####Returns

HTTP Status Code	Description
200	score request successfully changed
401	Authentication Error/Access Denied
404	Request id not found
415	Media Type or Output Format Not Supported
500	Server Failure
501	Service/Method not implemented

#####Comment Changes the score request with id {id}; the request body contains the score request content with the required changes If request with id {id} does not exist 404 has to be returned.

####DELETE

#####URL comment/{id}

#####Method DELETE

#####Request Body application/json, application/xml, text/xml

#####Returns

HTTP Status Code	Description
204	No content (successfully deleted)
401	Authentication Error/Access Denied
404	Request id not found
415	Media Type or Output Format Not Supported
500	Server Failure
501	Service/Method not implemented

#####Comment Deletes the score request with id {id}; the request body contains the score request id.

###CALLBACK related Methods

####POST

#####URL callback

#####Method POST

#####Request Body application/json, application/xml, text/xml

#####Returns

HTTP Status Code	Description
201	CALLBACK request successfully created
401	Authentication Error/Access Denied
415	Media Type or Output Format Not Supported
500	Server Failure
501	Service/Method not implemented

#####Comment The request body contains the field of the original request where the id of the original request is name “requestId”, a callBackStatus attribute and callbackText is added which identify the changes done to the request by the server. If files or URLs are part of the original request they are not part of the request body.

###Querying individual translation, comment and score attributes

A server is required to implement a specific access method for each attribute of the three requests (translation, comment, score).

#####URL {request-method}/{attribute}/{id}

#####Method GET

#####Request Body application/json, application/xml, text/xml

#####Returns

HTTP Status Code	Description
200	Request id found
401	Authentication Error/Access Denied
404	Request id not found
415	Media Type or Output Format Not Supported
500	Server Failure
501	Service/Method not implemented

#####Comment Returns the attribute of translation request with id {id} for {request-method} where request-method is one of the following: translation, score or comment. Attribute is an allowed attribute name.

Example:

score/crowd/2b575fdc-f6af-4b9e-850d-9dc0884c6595

returns the crowd attribute value of score with id 2b575fdc-f6af-4b9e-850d-9dc0884c6595.

###TAUS Translation API translation (V1.4) request methods

The following table describes the basic methods supported by API Version 1.4. This section is only contained for historical reasons. Prior version can be found at https://labs.taus.net/interoperability/taus-translation-api.

API Domain	Service	Typical Use Cases	Required
/translation/*	Get and submit translations	Almost all systems will implement this API	Yes
/im/*	Real-time message translation	IM, SMS and chat translation services.	No
/comment/*	View and submit comments about translations	Crowd translation services, professional translation services that allow user feedback, comments or discussion.	No
/score/*	View and submit score for translations	Crowd and professional translation services that allow user feedback and/or professional translator QA services, as well as moderated crowd translation systems.	No
/request/*	View and manage task queue on the translation server	This is used to expose the request queue to client applications, for example a web app that enables translators to see pending requests, or enables a client application to monitor task progress.	No