Authorisation

This API uses HTTP basic authorisation and most of its methods can only be successfully called by passing a valid username and password to Tethras as part of the HTTP request. Use your HTTP client's HTTP Basic Authorisation facilities for supplying an API request with the username and password.

For example: When using curl from the command line, the -u option is used to specify username and password. When using curllib from PHP, set the username password option like this:

If authorisation fails then the API will return HTTP 401: 401 Authentication Required.

HTTP Response codes

All requests will return an HTTP response code as follows:

• Successful requests will return HTTP 200 OK
• Requests that fail authorisation will return HTTP 401 Unauthorized
• Requests that fail for an unexpected reason may return HTTP 500 Internal Server Error

JSON Response Data

Most methods return data to the caller in a JSON format. All JSON response packets follow the following general format:

Field	Description
data	This field contains further method specific response data in JSON format, see each method's documentation for more details.
result_message	A readable, method specific response message
result_code	A code that indicates whether the request was successful, either 'ok', 'failed' or 'invalid argument'

API Methods

The following is a list of the methods that the Tethras API supports.

Create Project

This method creates a new project on the Tethras system with no files. This process may take a few minutes, a client can at any stage check a project’s via a call to the Get Project Status method.

Handler:	/api/create_project
HTTP Method:	POST
Authorization:	HTTP Basic Auth. (username & password)
Response Format:	JSON

Arguments:

Argument	Allowed Value	Required	Description
projName	string	required	A name for the new project.
platform	one of: 'iOS' 'Mac OS' 'Android' 'Windows Phone' 'BlackBerry' 'Subtitles' 'Other'	required

Return Values:

Name	Description
project_id	A unique identifier that identifies the newly added project.

Curl Example:

Expected Response:

The project_id field contains the identifier of the newly added project, this id is important and will passed as arguments to other API methods.

Example Error Response:

Add New Project

This method uploads a new project into the system. The caller must specify the projects name and provide a zip file of the content to be localized. Once a project has created a project it starts to process it by parsing its files etc. This process may take a few minutes, a client can at any stage check a project's via a call to the Get Project Status method.

Handler:	/api/add_project
HTTP Method:	POST
Authorization:	HTTP Basic Auth. (username & password)
Response Format:	JSON

Arguments:

Argument	Allowed Value	Required	Description
projName	string	required	A name for the new project.
zipFile	Zip file data	required	A zip file of all of the project's localizable content.
platform	one of: 'iOS' 'Mac OS' 'Android' 'Windows Phone' 'BlackBerry' 'Subtitles' 'Other'	required

Return Values:

Name	Description
project_id	A unique identifier that identifies the newly added project.

Curl Example:

Expected Response:

The project_id field contains the identifier of the newly added project, this id is important and will passed as arguments to other API methods.

Example Error Response:

Update Project

This method uploads new files to an already created project. The caller must specify the projects id and provide a zip file of the content to be localized. This process may take a few minutes, a client can at any stage check a project's via a call to the Get Project Status method.

Handler:	/api/update_project
HTTP Method:	POST
Authorization:	HTTP Basic Auth. (username & password)
Response Format:	JSON

Arguments:

Argument	Allowed Value	Required	Description
proj_id	string	required	The projects id.
zipFile	Zip file data	required	A zip file of all of the project's localizable content.

Return Values:

None

Curl Example:

Expected Response:

Example Error Response:

Add File to Project

This method uploads files to an already created project. The caller must specify the projects id and provide a localizable resource file, or a zip file containing localizable resource files. This process may take a few minutes, a client can at any stage check a project’s via a call to the Get Project Status method.

Handler:	/api/add_file_to_project
HTTP Method:	POST
Authorization:	HTTP Basic Auth. (username & password)
Response Format:	JSON

Arguments:

Argument	Allowed Value	Required	Description
proj_id	string	required	The projects id.
file_data	file data	required	A localizable resource file, or a zip file containing localizable resource files.

Return Values:

None

Curl Example:

Expected Response:

Example Error Response:

Get Project Status

This method fetches the current state of a specified project. The project is identified by its project_id.

Handler:	/api/project_status
HTTP Method:	POST
Authorization:	HTTP Basic Auth. (username & password)
Response Format:	JSON

Arguments:

Argument	Allowed Value	Required	Description
project_id	string	required	The id of the project in question.

Return Values:

Name	Description
current_status	The project's internal system status, one of: new updating up-to-date in-production in-translation up-to-date error processing deleting
display_status	The project's high-level display status which is more 'user friendly' thanthe current_status field. Can be one of: new purchased processing awaiting_reply complete update deleted

Curl Example:

Expected Response:

The project_status field contains the project's status.

Example Error Response:

Get Supported Languages

This method returns a list of the languages that are supported by Tethras for localization, detailing their language codes and names.

Handler:	/api/supported_languages
HTTP Method:	POST
Authorization:	HTTP Basic Auth. (username & password)
Response Format:	JSON

Response:

Name	Description
supported_languages	A list of supported languages.
lang_code	A language's code.
language	A language's name.

Curl Example:

Expected Response (Truncated):

Add Language to Basket

This method adds the specified languages to the project's shopping basket. As soon as a language is added to the basket the system starts processing, the client can determine when this processing completes by checking the projects status via a request using the Get Project Status Method. No more languages should be added or removed until this processing has completed. Multiple languages can be added at a time by using duplicate parameters.

Handler:	/api/add_to_basket
HTTP Method:	POST
Authorization:	HTTP Basic Auth. (username & password)
Response Format:	JSON

Arguments:

Argument	Allowed Value	Required	Description
project_id	string	required	The id of the project in question.
lang_code (multiple allowed)	string, language code.	required	one of the language codes returned from /api/supported_languages

Curl Example:

Expected Response:

Example Error Response:

Remove Language from Basket

This method initiates the removal of the specified language from an project's basket. Once the system starts processing, the client can determine when this processing completes by checking the projects status via a request using the Get Project Status Method. No more languages should be added or removed until this processing has completed.

Handler:	/api/remove_from_basket
HTTP Method:	POST
Authorization:	HTTP Basic Auth. (username & password)
Response Format:	JSON

Arguments:

Argument	Allowed Value	Required	Description
project_id	string	required	The id of the project in question.
lang_id	string, language code.	required	The id of the language in question

Curl Example:

Expected Response:

Example Error Response:

Download Translations

This method allows the client to download translations as a zip archive.

Handler:	/api/download_translations_zip
HTTP Method:	GET
Authorization:	HTTP Basic Auth. (username & password)
Response Format:	ZIP Stream or JSON

Arguments:

Argument	Allowed Value	Required	Description
project_id	string	required	The id of the project in question.
lang_code	string, language code.	required	One of the language codes returned from /api/supported_languages.

Curl Example:

Expected Response:

Example Error Response:

Pricing Information

This method returns some information about the Tethras pricing structure.

Handler:	/api/pricing
HTTP Method:	GET
Authorization:	HTTP Basic Auth. (username & password)
Response Format:	JSON

Arguments:

None

Return Values:

Name	Description
minimum_job_cost	The per language price.
pricing	A list of pricing information, one for each supported language.
For each Supported Language:
code	The language code, eg.g fr, de etc.
language	The language name, e.g. French, German etc.
basic	The word rate for the 'Basic' translation level (this was previously called 'Standard')
professional	The word rate for the 'Professional' translation level.
ultra	The word rate for the 'Ultra' translation level.
specialist	The word rate for the 'Specialist' translation level.

Curl Example:

Expected Response (Truncated):