Exposing Pontoon Data Through API

Application Programming Interface, or API for short, is how computer programs talk to each other. As of the last week of September Pontoon exposes data about projects and locales through a publicly available API.

In this first iteration we focused on one use-case outlined in bug 1302053.

It would be really useful being able to retrieve information from Pontoon via API. Interesting queries:

• Stats for a locale: supported projects, status of each project.
• Stats for a project: supported locales, incomplete locales, complete locales.

After a thorough discussion and research we settled on using GraphQL. GraphQL is both a language for describing the API queries and a runtime for running these queries against the real data. It was created by Facebook and has lately seen a lot of adoption due to its declarative nature, predictability of results and the GraphiQL IDE which allows to easily explore the API and test different queries in the browser.

With GraphQL, the users of the API have precise control over the data the API returns. In the following example, the API will return a list of all active projects and for each project listed only its name will be retrieved.

query {
    projects {
        name
    }
}

It’s also easy to query data spanning multiple relations in the data model. In the following example for every active project the API will also return a list of locales for which the project has been enabled.

query {
    projects {
        name
        localizations {
            locale {
                name
            }
        }
    }
}

Queries can be made using GET and POST requests alike. Here are a few real-life examples which illustrate what’s already possible in the current version of the API:

• All active project names with number of missing strings.
• Total and missing strings for all active projects in Italian.
• The total number of strings for each locale on Mozilla.org.
• Total and missing strings across all locales for Firefox for iOS.

In an effort to make it easy to get started with the API and make the available data discoverable, the first milestone of the API ships with the GraphiQL IDE. GraphiQL is a query editor which runs in the browser. You can use it to explore the API and test queries in the browser. Currently it’s only available in local deployments of Pontoon at http://localhost:8000/graphql. In the future we plan to enable it on production as well.

The end goal is to expose almost all data that Pontoon stores and processes: translations and suggestions, contributors’ activity, notifications and others.  Ultimately the API will also allow writing to the database and will become the back-end for the future versions of Pontoon. We’d like to keep the development of the API use-case-driven. If you’re interested in creating a report or an extension which pulls data from Pontoon please let us know about your use-case! We’d like to prioritize the upcoming features to best serve the needs of the community. Refer to the L10n:Pontoon/API wikipage for more information about the planning process.