Tethas API - Documentation

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:

curl_setopt($process, CURLOPT_USERPWD, $username . ":" . $password);

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:

{
"data": null,
"result_message": "a message",
"result_code": "ok"
}

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.

Project Methods

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:

curl https://www.tethras.com/api/add_project -u"apiuser@yahoo.co.uk:eggs" -F projName=”TestProject2” -F platform=iOS

Expected Response:

{"data": {"project_id": 31258096}, "result_message": "", "result_code": "ok"}

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:

{"data": {"project_id": ""}, "result_message": "Platform must be specified”, "result_code”:”failed”}

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:

curl https://www.tethras.com/api/add_project -u"apiuser@yahoo.co.uk:eggs" -F projName=”TestProject2” -F platform=iOS -F zipFile=@test_fast.zip

Expected Response:

{"data": {"project_id": 31258096}, "result_message": "New project added", "result_code": "ok"}

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:

{"data": {"project_id": ""}, "result_message": "No or Invalid Zip File.", "result_code": "failed"}

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:

curl https://www.tethras.com/api/update_project -u"apiuser@yahoo.co.uk:eggs" -F proj_id=”123456” -F zipFile=@test_fast.zip

Expected Response:

{"data": {}, "result_message": "", "result_code": "ok"}

Example Error Response:

{"data": {}, "result_message": "No or Invalid Zip File.", "result_code": "failed"}

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:

curl https://www.tethras.com/api/update_project -u"apiuser@yahoo.co.uk:eggs" -F proj_id=”123456” -F file_data=@Localizable.strings

Expected Response:

{"data": {}, "result_message": "", "result_code": "ok"}

Example Error Response:

{"data": {}, "result_message": "No file provided", "result_code": "failed"}

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:

curl https://www.tethras.com/api/project_status?project_id=31258096 -u"apiuser@yahoo.co.uk:eggs"

Expected Response:

{"data": {"status": "up-to-date", "project_status": "uploaded"}, "result_message": "", "result_code": "ok"}

The project_status field contains the project's status.

Example Error Response:

{"data": {"status": "unknown", "project_status": "unknown"}, "result_message": "No App for project_id 1131258096", "result_code": "invalid argument"}

Languages Methods

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:

curl https://www.tethras.com/api/supported_languages -u"apiuser@tethras.com:eggs"

Expected Response (Truncated):

{"data": {"supported_languages": [{"lang_code": "ar", "language": "Arabic"}, {"lang_code": "ca", "language": "Catalan"}, {"lang_code": "cs", "language": "Czech"}, {"lang_code": "da", "language": "Danish"} …. ]}, "result_message": "", "result_code": "ok"}

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:

curl -u"apiuser@tethras.com:eggs" -d"project_id=31258096&lang_code=ru&lang_code=fr" https://www.tethras.com/api/add_to_basket

Expected Response:

{"data": null, "result_message": "Language added to basket.", "result_code": "ok"}

Example Error Response:

{"data": null, "result_message": "No project for project_id 31258096", "result_code": "failed"}

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:

curl -u"apiuser@tethras.com:eggs" -d"project_id=31258096&lang_id=23768954" https://www.tethras.com/api/remove_from_basket

Expected Response:

{"data": null, "result_message": "Language removed from basket.", "result_code":"ok"}

Example Error Response:

{"data": null, "result_message": "Language ko not in basket", "result_code": "failed"}

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:

curl -u"apiuser@tethras.com:your-password" "https://www.tethras.com/api/download_translations_zip?project_id=22639&lang_code=ru" > russian.zip

Expected Response:

zip file stream

Example Error Response:

{"data": null, "result_message": "No download for language ru", "result_code": "failed"}

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:

curl -u"apiuser@tethras.com:your-password" "https://www.tethras.com/api/pricing

Expected Response (Truncated):

{"data": {"minimum_job_cost": "9.99", "pricing": [{"specialist": "0.28", "code":"fr", "professional": "0.12", "language": "French", "basic": "0.08", "ultra": "0.18"}, {"specialist": "0.28", "code": "de","professional": "0.12", "language": "German", "basic": "0.08", "ultra": "0.18"}, ..., ]}, "result_message": "", "result_code": "ok"}