Using Pootle API¶

In order to use the Pootle API it is necessary to know how some things, like the supported formats, available authentication methods or basic rules for performing queries.

Pootle API is created using Tastypie so you might need to refer to its documentation as well.

How to perform API queries¶

The structure of the API URLs is <SERVER>/api/<API_VERSION>/<QUERY> where:

Placeholder	Description
<SERVER>	The URL of the Pootle server
<API_VERSION>	Version number of the API
<QUERY>	Resource query URI

So the API can be queried using URLs like:

http://pootle.locamotion.org/api/v1/translation-projects/65/

List matching a criteria¶

For some resources it is also possible to narrow down the list by providing a query string containing filters provided by Tastypie (that actually are Django ORM Field Lookups).

In this case the structure of the API URLs is <SERVER>/api/<API_VERSION>/<RESOURCE>/?<CRITERIA> where <CRITERIA> is the query string. For example:

http://pootle.locamotion.org/api/v1/units/?mtime__month=05&mtime__day=12&state__exact=200

Authentication¶

Pootle requires authentication for accessing its API.

The method used for authentication is HTTP Basic Authentication which requires providing a username and a password (the same ones used for Pootle login).

Note

Other authentication methods can be added in the future.

Authorization¶

The Pootle API allows to interact with resources that represent some of the data handled internally by Pootle. In order to avoid all users access or alter data they are not meant to, the Pootle API checks if the visitor has enough permissions to perform the requested actions on the resources. The permissions used for these checks are the same permissions used in Pootle for regular users.

For some particular resources some other checks can be done to allow or deny performing the requested action. For example the visitors can only see the User resource for the user that they used to log in the Pootle API.

Formats¶

By default Pootle API returns only JSON replies. It is possible to use all the formats supported by Tastypie.

Tools and libraries¶

Translate is currently developing a client for Pootle API, but there are several other libraries and programs capable of interacting with Pootle API. For example here is an example script that uses Slumber to retrieve and print the list of used languages in Pootle:

import slumber

# Change the following to match your Pootle URL, your username and password.
API_URL = "http://127.0.0.1:8000/api/v1/"
AUTH=('admin', 'admin')

api = slumber.API(API_URL, auth=AUTH)

# Get all languages data.
lang_data = api.languages.get()

for lang in lang_data["objects"]:
    print(lang["code"])

Note

Remember to install Slumber in order to run the previous code.