Skip to content
This repository
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 315 lines (253 sloc) 13.212 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314
.. -*- mode:rst -*-

.. _tech-api-v1:

===============================
 Transifex API v1 (deprecated)
===============================

.. note::

  This document describes Transifex API v1, which is no longer used.
  There are also docs for the :ref:`development version
  <tech-api-devel>`.

Transifex offers an extensive API which is currently being used by Transifex
itself and the ``transifex-client`` to perform some of the most common
operations such as pulling information about projects and translation
resources and uploading or downloading translation files. The API calls are
ReST compliant and make use of the most common HTTP methods such as GET, POST,
PUT and DELETE.

.. _api_authentication-v1:

Authentication
==============

All of the API calls on Transifex require the user to be authenticated with
Transifex in order to complete them. Currently, the API supports `HTTP Basic
Authentication <http://en.wikipedia.org/wiki/Basic_access_authentication>`_
and it's also sharing login information with django's built in authentication
system that's being used on Transifex. All external applications should make
use of the HTTP Basic Authentication if they need to perform some operations
through the Transifex API.

Part of the development roadmap for Transifex is to add support for other
authentication methods as well, such as authentication tokens in order to
avoid forcing users to share their login credentials with third party
applications. Until then, the only available method is the one stated above.


API Sections
============

The Transifex API is divided in sections, based on the application it refers to
and the models it interacts with.

Storage
-------

This application handles file uploads and provides a way to store temporary
data from a file before we extract all it and save it into the database.

StorageHandler
~~~~~~~~~~~~~~

The major functionality of this handler is that it allows you to upload files
into transifex which later can be extracted and saved to the database,
updating an existing resource.


**URL** */api/storage/*

+--------+-------------------------------------------------------------------+
| METHOD | FUNCTION |
+========+===================================================================+
| GET | .. py:function:: read(self, request[, uuid=None]) |
| | |
| | Returns a list of all StorageFile objects or a single object if a |
| | uuid is specified. |
+--------+-------------------------------------------------------------------+
| POST | .. py:function:: create(self, request[, uuid=None]) |
| | |
| | API call for uploading a file via POST. If a uuid is provided and |
| | this matches another file, it gets overwritten. |
+--------+-------------------------------------------------------------------+
| DELETE | .. py:function:: delete(self, request[, uuid=None]) |
| | |
| | Deletes file by storage UUID. |
+--------+-------------------------------------------------------------------+

When doing POST requests, if the requests are successful you'll get a JSON
response containing the UUID of the created StorageFile. If you want to
extract the strings from the file you need to do a POST request with this UUID
to the :ref:`project-resource-handler`.

Projects
--------

The *Projects* application provides project specific operations. From the
implemented handlers, you can perform CRUD operations on projects and
also upload source translation files under a project and create the associated
translation resources.

ProjectHandler
~~~~~~~~~~~~~~

The ProjectHandler is the one used to perform CRUD operations on the project
objects. You can get information on existing projects, create new ones or
update existing ones with new information.

**URL** */api/project/project_slug/*

+--------+-------------------------------------------------------------------+
| METHOD | FUNCTION |
+========+===================================================================+
| GET | .. py:function:: read(self, request[, project_slug=None]) |
| | |
| | Get project details in json format. |
+--------+-------------------------------------------------------------------+
| POST | .. py:function:: create(self, request, project_slug) |
| | |
| | API call to create new projects based on JSON files. |
+--------+-------------------------------------------------------------------+
| PUT | .. py:function:: delete(self, request, project_slug) |
| | |
| | API call to update project details via JSON file. |
+--------+-------------------------------------------------------------------+

When requesting a project's details, you'll be offered a JSON file in the
following format (this file is for the Transifex project):

.. code-block:: guess

{
"description": "An open translation platform.",
"created": "2009-04-21 08:12:16",
"slug": "transifex",
"owner": {
"username": "diegobz",
"email": "diegobz@transifex.com"
},
"anyone_submit": false,
"long_description": "Transifex is web system to manage translations from
various distributed repositories.",
"resources": [
{
"i18n_type": "PO",
"created": "2010-10-04 12:45:31",
"source_language": {
"code_aliases": " ",
"code": "en",
"name": "English"
},
"slug": "txo",
"name": "Transifex core"
},
{
"i18n_type": "PO",
"created": "2010-10-13 14:37:45",
"source_language": {
"code_aliases": " ",
"code": "en",
"name": "English"
},
"slug": "txn",
"name": "Transifex.com"
}
],
"name": "Transifex"
}

Similarly, whenever you need to create a new project or update an existing
one, you can include a JSON file when doing the POST or PUT request which must
be in the format stated above and it'll create or update the project with the
details included in the file.

.. _project-resource-handler:

ProjectResourceHandler
~~~~~~~~~~~~~~~~~~~~~~

This handler is one of the core parts of the Transifex API. It is used to
extract uploaded files, specified by their UUID, and create new translation
resources for these files.

**URL** */api/project/<project_slug>/files/*

+--------+-----------------------------------------------------------------------------------------+
| METHOD | FUNCTION |
+========+=========================================================================================+
| POST | .. py:function:: create(self, request, project_slug) |
| | |
| | Create new resource under project with slug <project_slug> by |
| | extracting the StorageFile with matching UUID. |
+--------+-----------------------------------------------------------------------------------------+
| UPDATE | .. py:function:: update(self, request, project_slug, resource_slug, language_code=None) |
| | |
| | Update resource translations of a project by the UUID of a StorageFile. |
+--------+-----------------------------------------------------------------------------------------+

In the POST data of the request you need to specify the ``UUID`` of the
StorageFile that you got as a response when you uploaded a file and as an
optional argument the slug (specified with the POST data variable ``slug``) of
the target resource that will be created (by default, the filename is used if
no slug is provided).

Resources
---------

FileHandler
~~~~~~~~~~~

The FileHandler simply takes care of providing an API call to export and
download translation files from Transifex. It offers a single GET method for
file downloads which is described below.

**URL** */api/project/<project_slug>/resource/<resource_slug>/<language_code>/file/*

+--------+--------------------------------------------------------------------------------------------+
| METHOD | FUNCTION |
+========+============================================================================================+
| GET | .. py:function:: read(self, request, project_slug, resource_slug=None, language_code=None) |
| | |
| | API Handler to export translation files from the database. |
+--------+--------------------------------------------------------------------------------------------+

ResourceHandler
~~~~~~~~~~~~~~~

The ResourceHandler is tied with the Resource model and allows CRUD operations
on the Resource model.


**URL** */api/project/project_slug/resource/resource_slug/*

+--------+-------------------------------------------------------------------------+
| METHOD | FUNCTION |
+========+=========================================================================+
| GET | .. py:function:: read(self, request, project_slug, resource_slug=None) |
| | |
| | Get resource details in JSON format. |
+--------+-------------------------------------------------------------------------+
| POST | .. py:function:: create(self, request, project_slug, resource_slug=None)|
| | |
| | Create new resource under project with slug=`project_slug` via POST. |
+--------+-------------------------------------------------------------------------+
| PUT | .. py:function:: delete(self, request, project_slug, resource_slug=None)|
| | |
| | API call to update resource details via JSON file. |
+--------+-------------------------------------------------------------------------+

When requesting the resource details from the server you should get a JSON
file like the following:

.. code-block:: guess

{
"name": "Transifex core",
"created": "2010-10-04 12:45:31",
"i18n_type": "PO",
"source_language": {
"code_aliases": " ",
"code": "en",
"name": "English"
},
"available_languages": [
{
"code_aliases": " sq-AL ",
"code": "sq",
"name": "Albanian"
},
{
"code_aliases": " bal-IR ",
"code": "bal",
"name": "Balochi"
},
...
{
"code_aliases": " te-IN ",
"code": "te",
"name": "Telugu"
},
{
"code_aliases": " uk-UA ",
"code": "uk",
"name": "Ukrainian"
}
],
"slug": "txo"
}

In order to update the resource details, you can issue a PUT request with a
file containing JSON formatting like the one displayed above. However, keep in
mind that it's not possible to change the available languages or the source
language of the resource.


StatsHandler
~~~~~~~~~~~~

**URLS**:

* */api/project/<project_slug>/resource/<resource_slug>/stats/*
* */api/project/<project_slug>/resource/<resource_slug>/stats/<lang_code>/*

+--------+----------------------------------------------------------------------------------+
| METHOD | FUNCTION |
+========+==================================================================================+
| GET | .. py:function:: read(self, request, project_slug, resource_slug, lang_code=None)|
| | |
| | This is used to display translation statistics for individual resources. |
+--------+----------------------------------------------------------------------------------+

If no language code is specified then statistics are displayed for all the
available languages of the resource, otherwise, if a language code is given
only the statistics for the matching language will be displayed. The
statistics include the completion percentage for each language, the number of
the strings translated and the date the language was last updated.





.. _Transifex.com: http://www.transifex.com/
Something went wrong with that request. Please try again.