L10n:Pontoon/API: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
(Milestones 2-5)
 
(25 intermediate revisions by 3 users not shown)
Line 1: Line 1:
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]).
==Description==


The tracking bug for all work related to the API for Pontoon is {{bug|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 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]).
 
==Overview==
{| class="wikitable"
! style="text-align: center;" | Milestone
! style="text-align: center;" | Theme
! style="text-align: center;" | Status
|-
| M1
| Projects and Locales
| ✓
|-
| M2
| User Notifications
|
|-
| M3
| Statistics over time
|
|-
| M4
| Contributors
|
|-
| M5
| Translation Memory
|
|-
| M6
| Translations
|
|-
|}


==Roadmap==
==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}}:  
===Milestone 1: Projects and Locales===
 
''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 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.


In future iterations, more use-case can be supported:
<bugzilla>
    {
        "id": "1302053",
        "include_fields": "id, summary, status, resolution, priority, assigned_to"
    }
</bugzilla>
 
===Milestone 2: User notifications===


* Exposing data which can be fetched by a SPA front-end
Use-cases:
** This will likely require pagination
* Getting the stream of notifications per authorized user


==Milestone 1==
* [[L10n:Pontoon-Tools|Michal's Pontoon Tools extension]]


''Complete, deployed on October 2, 2017.''
Queries:
 
* [[L10n:Pontoon-Tools#Data_sources|See Data sources section on the Pontoon Tools wiki]]
* Authentication (only return non-public data like notifications if the API consumer is authenticated)
 
===Milestone 3: Statistics over time===


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}}:  
Use-cases:


* Stats for a locale: supported projects, status of each project.
* Community Health, e.g.:
* Stats for a project: supported locales, incomplete locales, complete locales.
** Translation progress over time.
** Unreviewed suggestions progress over time.


<bugzilla>{
Queries:
    "f1":"blocked",
    "o1":"equals",
    "v1":"1395273",
    "include_fields": "id, summary, status, resolution, assigned_to, depends_on, blocks"
}</bugzilla>


==Milestone 2==
* [https://docs.google.com/document/d/1FlZLe8m2sFX6-AT9u_R8D4IODzcTNfx3d1QNaFzT1MQ/edit Get a number of strings per project within a period of time].
** Or a number of words.


Main theme: translations and pagination.
===Milestone 4: Contributors===


* Establish a good practice for paginating results.
Use-cases:
* 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==
* [https://docs.google.com/spreadsheets/d/1-QWPJovsag4eYghkK2MMo30wa7QzOOMQkZdIjXnfZGQ/edit#gid=532595279 Number of user groups per locale].


Main theme: contributors.
Queries:


* Query a single contributor (by email? unique key?)
* Query a single contributor (by email? unique key?)
** List recent activity: date, project, action, number of affected strings
** List contributor data: email, display name, permissions, settings
** Aggregate counts of: translated, suggested, fuzzy strings across all projects
** List recent activity: date, string, action
** Aggregate counts of: translated, unreviewed, fuzzy strings across all projects
** List of projects they contribute to
** List of projects they contribute to
*** Aggregate counts of: translated, suggested, fuzzy strings for each project
*** Aggregate counts of: translated, unreviewed, fuzzy strings for each project
* List all contributors on Pontoon
* List all contributors on Pontoon
* List all contributors for a locale
* List all contributors for a locale
* List all contributors for a project
* List all contributors for a project
* List all contributors for a localization (ProjectLocale)
===Milestone 5: Translation memory===
Use-cases:
* External services.
* Mozilla translators in non-Mozilla projects.
Queries:
* For a given source string, locale and minimum Levenshtein ratio, return a maximum number of results.
===Milestone 6: Translations===
Use-cases:
* Report translation status of a single page on mozilla.org
* Read-only data required by Pontoon.Next's Translate app
* Editing translations via Pontoon.Next's Translate app


==Milestone 4==
Queries:


Main theme: authentication.
* 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, unreviewed, 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.
* Add a translation for an Entity
** "approved" if the permissions are high enough
** "unreviewed" otherwise
* Approve/reject a suggestion.
 
<bugzilla>{
    "f1":"blocked",
    "o1":"equals",
    "v1":"1409704",
    "include_fields": "id, summary, status, resolution, priority, assigned_to"
}</bugzilla>


* List unread notifications for a logged-in user.
==Ideas==
A list of ideas to consider for future milestones.


==Milestone 5==
==Contact==


Main theme: mutations.
{| class="wikitable"
! style="text-align: center;" | Role
! style="text-align: center;" | Name
! style="text-align: center;" | IRC
|-
| Feature Owner
| Staś Małolepszy
| stas
|-
| Product Owner
| Matjaž Horvat
| mathjazz
|-
| Reviewer
| Adrian Gaudebert
| adrian
|}


* Add a suggested translation for an Entity.
;Mailing list
:[https://groups.google.com/forum/#!forum/mozilla.tools.l10n tools-l10n]
;IRC
:[irc://irc.mozilla.org/pontoon #pontoon]

Latest revision as of 22:08, 5 July 2018

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 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 Status
M1 Projects and Locales ✓
M2 User Notifications
M3 Statistics over time
M4 Contributors
M5 Translation Memory
M6 Translations

Roadmap

Milestone 1: Projects and Locales

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: User notifications

Use-cases:

Queries:

Milestone 3: Statistics over time

Use-cases:

  • Community Health, e.g.:
    • Translation progress over time.
    • Unreviewed suggestions progress over time.

Queries:

Milestone 4: Contributors

Use-cases:

Queries:

  • Query a single contributor (by email? unique key?)
    • List contributor data: email, display name, permissions, settings
    • List recent activity: date, string, action
    • Aggregate counts of: translated, unreviewed, fuzzy strings across all projects
    • List of projects they contribute to
      • Aggregate counts of: translated, unreviewed, 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 5: Translation memory

Use-cases:

  • External services.
  • Mozilla translators in non-Mozilla projects.

Queries:

  • For a given source string, locale and minimum Levenshtein ratio, return a maximum number of results.

Milestone 6: Translations

Use-cases:

  • Report translation status of a single page on mozilla.org
  • Read-only data required by Pontoon.Next's Translate app
  • Editing translations via 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, unreviewed, 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.
  • Add a translation for an Entity
    • "approved" if the permissions are high enough
    • "unreviewed" otherwise
  • Approve/reject a suggestion.
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%);


Ideas

A list of ideas to consider for future milestones.

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.mozilla.org/index.php?title=L10n:Pontoon/API&oldid=1196753"