TermBase API

The TermBase API is composed of 7 endpoints:

List Terms

This endpoint is accessible by the read-write Project API key and is used to list terms.

/api/projects/:project_token/terms.format [GET]

Where format is one of xml, json, or yaml.

Pagination

This resource is paginated and serves 250 Terms per page. You can specify further page using the ?page parameter. Note that page numbering is 1-based and that omitting the ?page parameter will return the first page.

Link Header

The pagination information is included in the Link header. You can use the Link Header in order to know which page is next and which page is the last one, instead of constructing your own URLs.

For instance, let’s make a curl request to the TermBase API:

$ curl -I "https://webtranslateit.com/api/projects/api_token/terms.json"

The -I parameter indicates that we only care about the headers, not the actual content. In examining the result, you’ll notice some information in the Link header that looks like this:

Link: <https://webtranslateit.com/api/projects/api_key/terms.json?page=2>; rel="next",
  <https://webtranslateit.com/api/projects/api_key/terms.json?page=20>; rel="last"

The possible rel values are:

  • next: Shows the URL of the immediate next page of results.
  • last: Shows the URL of the last page of results.
  • first: Shows the URL of the first page of results.
  • prev: Shows the URL of the immediate previous page of results.

Here’s another example of the Link Header when browsing the 3rd page:

$ curl -I "https://webtranslateit.com/api/projects/api_token/terms.json?page=3"
Link: <https://webtranslateit.com/api/projects/api_key/terms.json?page=4>; rel="next",
  <https://webtranslateit.com/api/projects/api_key/terms.json?page=9>; rel="last",
  <https://webtranslateit.com/api/projects/api_key/terms.json?page=1>; rel="first",
  <https://webtranslateit.com/api/projects/api_key/terms.json?page=2>; rel="prev"

This resource is paginated and serves 250 Terms per page. In the server response headers, you will find Link, with a link for an API call to the next and last pages.

Parameters

page: Page number.

Example query:

https://webtranslateit.com/api/projects/api_key/terms

Example response with JSON:

[
  {
    "id": 1234,
    "text": "User",
    "description": "Someone using the WebTranslateIt service.",
    "created_at": "2010-02-09T23:23:45Z",
    "updated_at": "2011-10-28T13:54:13Z",
  },
  {
    "id": 1235,
    "text": "Segment",
    "description": "A portion of text to translate.",
    "created_at": "2010-02-09T23:23:45Z",
    "updated_at": "2011-10-28T13:54:13Z",
  }
]

Show Term

This endpoint is only accessible by the read-write Project API key and is used to show a term.

/api/projects/:project_token/terms/:term_id.format [GET]

Where format is one of xml, json or yaml.

Example response with JSON:

{
  "id": 1234,
  "text": "User",
  "description": "Someone using the WebTranslateIt service.",
  "created_at": "2010-02-09T23:23:45Z",
  "updated_at": "2011-10-28T13:54:13Z",
}

Example Implementation in Ruby

require "net/http"
http = Net::HTTP.new("webtranslateit.com", 443)
request = Net::HTTP::Get.new("/api/projects/:api_token/terms/:term_id")
http.request(request)

Example Implementation in PHP

<?php
$api_key = "sekret";
$term_id = "1234";
$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_URL, "https://webtranslateit.com/api/projects/" . $api_key . "/terms/". $term_id . ".json");
$response = curl_exec($ch);
$p = json_decode($response, true);
print_r($p);
curl_close($ch);
?>

Create Term

This endpoint is only accessible by the read-write Project API key and is used to create a new term.

/api/projects/:project_token/terms [POST]

Parameters

A JSON object modelled after the following:

{
  "text": "Term",
  "description": "An optional description"
}

The description field is optional. If everything goes Well, WebTranslateIt will respond with 201 Created in the header and a JSON representation of the term just created in the body.

You can also create one or several Term Translations while creating a Term by passing an optional array of Translation:

{
  "text": "Term",
  "description": "An optional description",
  "translations": [
  {
    "locale": "fr",
    "text": "Terme",
    "description": "La traduction de la description",
    "status": "approved"
  },
  {
    "locale": "es",
    "text": "Terminología",
    "description": "",
    "status": "refused"
  }
  ]
}

In this array of Translation, locale and text are mandatory. status is optional (defaults to proposed).

status can be one of approved, refused or proposed.

Example Implementation in Ruby

require "net/http"
require "json"
http = Net::HTTP.new("webtranslateit.com", 443)
http.use_ssl = true
request = Net::HTTP::Post.new("/api/projects/:api_token/terms", { "Content-Type" => "application/json" })
request.body = { "text" => "term", "description" => "An optional description" }.to_json
http.request(request)

Example Implementation in PHP

<?php
$api_key = "sekret";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://webtranslateit.com/api/projects/" . $api_key . "/terms");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, array("text" => "term", "dev_comment" => "An optional description"));
$response = curl_exec($ch);
print_r($response);
curl_close($ch);
?>

Update Term

This endpoint is only accessible by the read-write Project API key and is used to update an existing term.

/api/projects/:project_token/terms/:term_id [PATCH]

Parameters

A JSON object modelled after the following:

{
  "text": "Term",
  "description": "An optional description"
}

The description field is optional. Only provided fields will be modified.
If everything goes Well, WebTranslateIt will respond with 202 Accepted in the header and a JSON representation of the term just updated in the body.

Example Implementation in Ruby

require 'net/http'
require 'json'
http = Net::HTTP.new('webtranslateit.com', 443)
http.use_ssl = true
request = Net::HTTP::Put.new("/api/projects/:api_token/terms/:term_id", { "Content-Type" => "application/json" })
request.body = { "text" => "Term", "description" => "An optional description" }.to_json
http.request(request)

Example Implementation in PHP

<?php
$api_key = "sekret";
$term_id = "1234";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://webtranslateit.com/api/projects/" . $api_key . "/terms/" . $term_id);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PATCH");
curl_setopt($ch, CURLOPT_POSTFIELDS, array("text" => "Term", "description" => "An optional description"));
$response = curl_exec($ch);
print_r($response);
curl_close($ch);
?>

Delete Term

This endpoint is only accessible by the read-write Project API key and is used to delete a term and its translations.

/api/projects/:project_token/terms/:term_id [DELETE]

Example Implementation in Ruby

require "net/http"
http = Net::HTTP.new("webtranslateit.com", 443)
request = Net::HTTP::Delete.new("/api/projects/:api_token/terms/:term_id")
http.request(request)

Example Implementation in PHP

<?php
$api_key = "sekret";
$term_id = "1234";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://webtranslateit.com/api/projects/" . $api_key . "/terms/" . $term_id);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
$response = curl_exec($ch);
print_r($response);
curl_close($ch);
?>

TermBase to TBX

This endpoint is accessible by both the read-write and read-only Project API keys and is used to download a termbase as a TermBase Exchange file (TBX).

/api/projects/:project_token/terms/to_tbx [GET]

For more information about TBX files, please refer to the TBX specifications.

An optional parameter, locale=xx can be passed to get a TBX file containing only the source_locale and locale language pairs.

TermBase to CSV

This endpoint is accessible by both the read-write and read-only Project API keys and is used to download a termbase as a Comma Separated Value file (CSV).

/api/projects/:project_token/terms/to_csv [GET]

For more information about CSV files, please refer to the CSV specifications.

An optional parameter, locale=xx can be passed to get a CSV file containing only the source_locale and locale language pairs.