Skip to content

JSON API

Pascal Chevrel edited this page May 2, 2016 · 12 revisions

Transvision JSON API (Transvision >=3.4)

Transvision allows external tools to retrieve data through a JSON API

Please note that:

  • Data generated as JSON or JSONP output is sent with CORS headers.
  • JSON data is sent with the application/json Mime Type
  • JSONP data is sent with the application/javascript Mime Type

The format of a Transvision query is as such:

api/<api version>/<service requested>/<parameter 1>/<parameter 2>/<parameter x>/?optional_parameter1=foo&optional_parameter2=bar

A malformed query generates a response with an HTTP of 400 instead of 200 and the returned JSON contains information about what was incorrectly set in the query.

Examples:

There are currently 8 services in our first version of the API (v1):

  • entity: Return all translations for an entity (equivalent to /string/ JSON API)
  • locales: Return the list of locales for a repository
  • repositories: Return the list of repositories supported by the API
  • search: Search on repositories (equivalent to current JSON API on main page for strings and entities)
  • suggestions: Return string matches from both source and target languages, currently used to provide suggestions while the user types in the main searchbar.
  • tm: Translation memory, similar to the Amagama service
  • Transliteration: Transforms strings from a format to another
  • versions: returns the different versions of the API with their status (beta, stable, deprecated)

Entity search (entity)

This service returns the translation of a string in a Mozilla repository for which we know the entity reference in all of the languages available.

/api/v1/entity/<repository>/?id=<unique ID for entity>

Example:

https://transvision.mozfr.org/api/v1/entity/gaia_1_4/?id=apps/fl/pick.properties:no-installed-ringtones

This API is mostly useful to Mozilla translation tools (e.g. Mozilla Translator) since you need to be able to build the correct unique ID for the entity which is based on its path in the Mozilla repository.

Locales available (locales)

This service returns the list of locales available in Transvision for a repository

/api/v1/locales/<repository>/

Example:

https://transvision.mozfr.org/api/v1/locales/gaia_1_4/

Repositories available (repositories)

This service returns the list of repositories supported by Transvision

/api/v1/repositories/

Example:

https://transvision.mozfr.org/api/v1/repositories/

Starting with version 3.10, this service can also return the list of repositories covered by a locale: /api/v1/repositories/fr/

Example:

https://transvision-beta.mozfr.org/api/v1/repositories/fr/

General search (search)

This service performs a search on a repository and returns the list of strings matching this search, with the unique identifier of the string as a key. This is the strict equivalent of the old Transvision API (before version 3.4) which allowed returning a search via the website as a JSON source by adding &json to the url. The old service is discontinued and redirected transparently to the new API.

Here is the syntax:

/api/v1/search/<search type>/<repository>/<source locale>/<target locale>/<search terms>/?<extra_parameter=1>

Example:

https://transvision.mozfr.org/api/v1/search/strings/central/en-US/fr/Add%20bookmark/?case_sensitive=1

Starting with version 3.10: In addition to the real repositories, there is a virtual "global" repository that returns results from all the repositories supported for the locale, e.g.:

https://transvision-beta.mozfr.org/api/v1/search/strings/global/en-US/fr/Add%20bookmark/

There are 3 extra parameters that can be set:

  • case_sensitive: Make a case sensitive search.
  • perfect_match: Return only strings that match perfectly the searched terms.
  • whole_word: Return only results that have whole words matching.

Suggestions

This service, provided a search term, returns matching strings from both the source and target languages. It's currently used to display suggestions to users while they type in the main search bar.

Results are ordered based on the Levenshtein distance between the searched string and the available matches. Results can be limited to a maximum number. If enough search results are available, API will return half results from source and half from the target language, otherwise it will try to display as many results as possible to reach the maximum number.

Here is the syntax:

/api/v1/suggestions/<repository>/<source locale>/<target locale>/<search terms>/?<extra_parameter=integer>

List of extra parameters:

  • max_results: an integer

Example:

https://transvision.mozfr.org/api/v1/suggestions/release/en-US/fr/Home%20page/?max_results=3

Translation Memory (tm)

This service allows returning search results that are only strings and which contain a quality index based on the Levenshtein distance between the searched string for the source locales and the results. The results can be limited to a maximum number and can also be limited to a minimum quality.

Here is the syntax:

/api/v1/tm/<repository>/<source locale>/<target locale>/<search terms>/?<extra_parameter=integer>

Starting with version 3.10: In addition to the real repositories, there is a virtual "global" repository that returns results from all the repositories supported for the locale, ex: https://transvision-beta.mozfr.org/api/v1/tm/global/en-US/fr/Cancel/

List of extra parameters:

  • max_results: an integer
  • min_quality: an integer

Example:

https://transvision.mozfr.org/api/v1/tm/release/en-US/fr/Home%20page/?max_results=3&min_quality=80

Transliteration

The API transforms a string to a format.

The syntax:

/api/v1/transliterate/<format>/<string>

Example:

https://transvision.mozfr.org/api/v1/transliterate/sr-Cyrl/Завиритe

List of supported formats:

  • sr-Cyrl. Transforms a string from Serbian cyrillic to Serbian latin.

API Versions (versions)

This API returns the status of the versions of the API with their status (beta, stable, deprecated).

Here is the syntax:

/api/v1/versions/

Example:

https://transvision.mozfr.org/api/v1/versions/

Something went wrong with that request. Please try again.