L10n:Pontoon/API

For now, this page serves as a scratchpad for documenting the research into different API solutions for Pontoon. Once one solution is chosen and implemented, this page will feature the documentation about this solution.

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.

We'll be considering three solutions: REST, GraphQL and GraphQL with Relay.

REST

REST has been the de facto standard of API design for the last 10-15 years.

Pros

• Easy to implement thanks to the Django REST Framework project
• Browsable API: http://restframework.herokuapp.com/
• Familiar to the consumers of the API
• The developer has the exact control over which fields and relations are exposed

Cons

• By default, all fields as decided by the developer, are exposed and transferred, resulting in increased bandwidth
  • Work-arounds exists, e.g. &fields=foo,bar
• Only the relations expected by the developer can be queried in a single query, e.g. `project/1/locales`
  • Other relations require multiple requests, which can't be optimized
• Requires versioning and documentation

GraphQL with Relay

Relay is a specification for cursor-based pagination which solves the problem of omitting items when switching between pages if items are being added quickly in real time to the DB. It works great for Facebook's use-case of showing a feed of news and updates.

Pros

• Pagination is guaranteed to not omit items which have been added to the DB while the user was looking at one page and then switched to another one
• Relay has good integration with React
• It's becoming a standard for pagination in GraphQL

Cons

• Pontoon's data doesn't change so quickly (projects, locales, entities) to actually require a solution this powerful.
  • Translations and suggestions may change more quickly, however.
• graphene_django doesn't handle ManyToMany fields well with Relay enabled; by default the `through` table adds another layer of edges to the graph, which becomes verbose very quickly
  • See https://github.com/graphql-python/graphene/issues/83
• Suffers from the N+1 queries problem for ForeignKeys and ManyToMany relationships
  • See https://github.com/graphql-python/graphene-django/issues/57
• De-optimizes `prefetch_related` and `select_related`
  • See https://github.com/graphql-python/graphene-django/issues/179