L10n:Pontoon/API
Exposing Pontoon's data through an API will enable external consumers to build tools, extensions and reports about translations. In the future, the API will serve as the backend for Pontoon.NEXT's SPA front-end. We chose an iterative approach to exposing the data. We start small with a small number of clear-focused use-cases in mind and expand the scope in subsequent iterations. The API is based on GraphQL (see discussion).
The tracking bug for all work related to the API for Pontoon is bug pontoon-api.
Roadmap
In Q3 2017, we'd like to make some data stored in Pontoon openly available for third-parties. The main driver is the use case from bug 1302053:
- Stats for a locale: supported projects, status of each project.
- Stats for a project: supported locales, incomplete locales, complete locales.
In future iterations, more use-case can be supported:
- Exposing data which can be fetched by a SPA front-end
- This will likely require pagination
- Getting the stream of notifications per authorized user
Milestone 1
Complete, deployed on October 2, 2017.
In the first iteration we'd like to make some data stored in Pontoon openly available for third-parties. The goals is to create an API endpoint supporting queries related to aggregate statistics per locale and per project. The main driver is the use case from bug 1302053:
- Stats for a locale: supported projects, status of each project.
- Stats for a project: supported locales, incomplete locales, complete locales.
| ID | Summary | Status | Resolution | Assigned to | Depends on | Blocks |
|---|---|---|---|---|---|---|
| 1302053 | Expose project status and information through API | RESOLVED | FIXED | Staś Małolepszy :stas | 1395273 | |
| 1403861 | [API] Hide aggregate statistics about Suggested strings | RESOLVED | FIXED | Staś Małolepszy :stas | 1377969 | 1395273 |
| 1407192 | [API] Enable GraphiQL IDE on production | RESOLVED | MOVED | 1395273 | ||
| 1409704 | [tracking] Pontoon API Milestone 2 | RESOLVED | WONTFIX | 1408625, 1409711, 1409723, 1409724 | 1395273 | |
| 1410387 | [API] Expose aggregate statistics about Suggestions | RESOLVED | MOVED | 1377969 | 1395273 |
5 Total; 0 Open (0%); 5 Resolved (100%); 0 Verified (0%);
Milestone 2
Main theme: translations and pagination.
- Establish a good practice for paginating results.
- List all Resources for a Project.
- List all Entities for a Resource.
- List all Translations for an Entity.
- Include status: approved, suggested, fuzzy.
- List all TranslatedResources for a Resource.
- Include aggregate statistics.
- List all TranslatedResources for a Locale.
- List all TranslatedResources for a ProjectLocale?
Milestone 3
Main theme: contributors.
- Query a single contributor (by email? unique key?)
- List recent activity: date, project, action, number of affected strings
- Aggregate counts of: translated, suggested, fuzzy strings across all projects
- List of projects they contribute to
- Aggregate counts of: translated, suggested, fuzzy strings for each project
- List all contributors on Pontoon
- List all contributors for a locale
- List all contributors for a project
Milestone 4
Main theme: authentication.
- List unread notifications for a logged-in user.
Milestone 5
Main theme: mutations.
- Add a suggested translation for an Entity.