L10n:Pontoon/API: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
No edit summary
(Remove the main tracking table in favor of per-milestone ones)
Line 2: Line 2:


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 [http://graphql.org/ GraphQL] (see [https://wiki.mozilla.org/index.php?title=L10n:Pontoon/API&oldid=1181890#Technology discussion]).
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 [http://graphql.org/ GraphQL] (see [https://wiki.mozilla.org/index.php?title=L10n:Pontoon/API&oldid=1181890#Technology discussion]).
==Tracking==
The tracking bug for all work related to the API for Pontoon is {{bug|pontoon-api}}.
<bugzilla>{
    "f1":"blocked",
    "o1":"equals",
    "v1":"1395273",
    "include_fields": "id, summary, status, resolution, assigned_to, depends_on"
}</bugzilla>


==Overview==
==Overview==
Line 19: Line 8:
! style="text-align: center;" | Theme
! style="text-align: center;" | Theme
! style="text-align: center;" | Date
! style="text-align: center;" | Date
! style="text-align: center;" | Tracking bug
! style="text-align: center;" | Status
! style="text-align: center;" | Status
|-
|-
Line 24: Line 14:
| Projects and Locales
| Projects and Locales
| September 2017
| September 2017
|
| ✓
| ✓
|-
|-
Line 29: Line 20:
| Translations (Read-Only)
| Translations (Read-Only)
| November 2017
| November 2017
| {{bug|1409704}}
|
|
|-
|-
Line 34: Line 26:
| Translations (Write)
| Translations (Write)
| January 2018
| January 2018
|
|
|
|-
|-
Line 39: Line 32:
| User Notifications
| User Notifications
| March 2018
| March 2018
|
|
|
|-
|-
Line 44: Line 38:
| Contributors
| Contributors
| May 2018
| May 2018
|
|
|
|-
|-
Line 49: Line 44:


==Roadmap==
==Roadmap==
[https://bugzilla.mozilla.org/buglist.cgi?list_id=13836645&short_desc=%5BAPI%5D&columnlist=short_desc%2Cbug_status%2Cassigned_to%2Cblocked%2Cdependson&resolution=---&query_based_on=pontoon-api-open&query_format=advanced&short_desc_type=allwords&component=Pontoon&known_name=pontoon-api-open All open API bugs.]


===Milestone 1===
===Milestone 1===
Line 58: Line 55:
* Stats for a locale: supported projects, status of each project.
* Stats for a locale: supported projects, status of each project.
* Stats for a project: supported locales, incomplete locales, complete locales.
* Stats for a project: supported locales, incomplete locales, complete locales.
<bugzilla>
    {
        "id": "1302053",
        "include_fields": "id, summary, status, resolution, priority, assigned_to"
    }
</bugzilla>


===Milestone 2===
===Milestone 2===
Line 86: Line 90:
     "o1":"equals",
     "o1":"equals",
     "v1":"1409704",
     "v1":"1409704",
     "include_fields": "id, summary, status, resolution, assigned_to, depends_on"
     "include_fields": "id, summary, status, resolution, priority, assigned_to"
}</bugzilla>
}</bugzilla>


Revision as of 12:50, 18 October 2017

Description

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).

Overview

Milestone Theme Date Tracking bug Status
M1 Projects and Locales September 2017 ✓
M2 Translations (Read-Only) November 2017 bug 1409704
M3 Translations (Write) January 2018
M4 User Notifications March 2018
M5 Contributors May 2018

Roadmap

All open API bugs.

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.
Full Query
ID Summary Status Resolution Priority Assigned to
1302053 Expose project status and information through API RESOLVED FIXED P3 Staś Małolepszy :stas

1 Total; 0 Open (0%); 1 Resolved (100%); 0 Verified (0%);


Milestone 2

Main theme: read-only translations and pagination.

Use-cases:

  • Report translation status of a single page on mozilla.org
  • Read-only data required by Pontoon.Next's Translate app

Queries:

  • Establish a good practice for paginating results.
  • List all Resources for a Project.
  • List all Entities for a Resource.
  • List all Translations into a given Locale for an Entity.
    • Include status: approved, suggested, fuzzy.
    • Allow filtering on status via params?
    • List all Translations for an Entity
  • List all TranslatedResources for a ProjectLocale
    • Include aggregate statistics.
    • List all TranslatedResources for a Resource.
    • List all TranslatedResources for a Locale.
Full Query
ID Summary Status Resolution Priority Assigned to
1408625 [API] Query for a project of a particular locale RESOLVED MOVED P3
1409711 [API] Establish a good practice for paginating results. RESOLVED MOVED P3
1409723 [API] Expose Resources and TranslatedResources RESOLVED MOVED P3
1409724 [API] Expose Entities and Translations RESOLVED MOVED P3

4 Total; 0 Open (0%); 4 Resolved (100%); 0 Verified (0%);


Milestone 3

Main theme: authenticated mutations.

Use-cases:

  • Editing translations via Pontoon.Next's Translate app

Queries:

  • Add a translation for an Entity
    • "approved" if the permissions are high enough
    • "suggested" otherwise
  • Approve/reject a suggestion.

Milestone 4

Main theme: user notifications.

Use-cases:

Queries:

  • List unread notifications for a logged-in user.

Milestone 5

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
  • List all contributors for a localization (ProjectLocale)

Milestone X

Main theme: statistics over time.

Contact

Role Name IRC
Feature Owner Staś Małolepszy stas
Product Owner Matjaž Horvat mathjazz
Reviewer Adrian Gaudebert adrian
Mailing list
tools-l10n
IRC
#pontoon
Retrieved from "https://wiki.allizom.org/index.php?title=L10n:Pontoon/API&oldid=1182460"