{"id":1183,"date":"2017-10-10T15:52:30","date_gmt":"2017-10-10T15:52:30","guid":{"rendered":"http:\/\/blog.mozilla.org\/l10n\/?p=1183"},"modified":"2017-10-10T18:18:20","modified_gmt":"2017-10-10T18:18:20","slug":"exposing-pontoon-data-through-api","status":"publish","type":"post","link":"https:\/\/blog.mozilla.org\/l10n\/2017\/10\/10\/exposing-pontoon-data-through-api\/","title":{"rendered":"Exposing Pontoon Data Through API"},"content":{"rendered":"<p><em>Application Programming Interface<\/em>, or API for short, is how computer programs talk to each other. As of the last week of September <a href=\"https:\/\/pontoon.mozilla.org\/\">Pontoon<\/a> exposes data about projects and locales through a <a href=\"http:\/\/mozilla-pontoon.readthedocs.io\/en\/latest\/dev\/api.html\">publicly available API<\/a>.<\/p>\n<p>In this first iteration we focused on one use-case outlined in <a href=\"https:\/\/bugzilla.mozilla.org\/show_bug.cgi?id=1302053\">bug 1302053<\/a>.<\/p>\n<blockquote><p>It would be really useful being able to retrieve information from Pontoon via API. Interesting queries:<\/p>\n<ul>\n<li>Stats for a locale: supported projects, status of each project.<\/li>\n<li>Stats for a project: supported locales, incomplete locales, complete locales.<\/li>\n<\/ul>\n<\/blockquote>\n<p>After a <a href=\"https:\/\/groups.google.com\/forum\/#!topic\/mozilla.tools.l10n\/R1S7Pk-c6uU\">thorough discussion<\/a> and <a href=\"https:\/\/wiki.mozilla.org\/index.php?title=L10n:Pontoon\/API&amp;oldid=1181890#Technology\">research<\/a> we settled on using <a href=\"http:\/\/graphql.org\/\">GraphQL<\/a>. 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.<\/p>\n<p>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.<\/p>\n<pre style=\"padding-left: 30px;\">query {\r\n    projects {\r\n        name\r\n    }\r\n}<\/pre>\n<p>It&#8217;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.<\/p>\n<pre style=\"padding-left: 30px;\">query {\r\n    projects {\r\n        name\r\n        localizations {\r\n            locale {\r\n                name\r\n            }\r\n        }\r\n    }\r\n}<\/pre>\n<p>Queries can be made using <a href=\"http:\/\/mozilla-pontoon.readthedocs.io\/en\/latest\/dev\/api.html#production-deployments\">GET and POST requests<\/a> alike. Here are a few real-life examples which illustrate what&#8217;s already possible in the current version of the API:<\/p>\n<ul>\n<li><a href=\"https:\/\/pontoon.mozilla.org\/graphql?query={projects{name,missingStrings}}\">All active project names with number of missing strings.<\/a><\/li>\n<li><a href=\"https:\/\/pontoon.mozilla.org\/graphql?query={locale(code:%22it%22){name,localizations{project{name}totalStrings,missingStrings}}}\">Total and missing strings for all active projects in Italian.<\/a><\/li>\n<li><a href=\"https:\/\/pontoon.mozilla.org\/graphql?query={project(slug:%22mozillaorg%22){name,localizations{locale{code,name}totalStrings}}}\">The total number of strings for each locale on Mozilla.org.<\/a><\/li>\n<li><a href=\"https:\/\/pontoon.mozilla.org\/graphql?query={project(slug:%22firefox-for-ios%22){name,totalStrings,missingStrings}}\">Total and missing strings across all locales for Firefox for iOS.<\/a><\/li>\n<\/ul>\n<p>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 <a href=\"https:\/\/github.com\/graphql\/graphiql\">GraphiQL IDE<\/a>. 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&#8217;s only available in <a href=\"http:\/\/mozilla-pontoon.readthedocs.io\/en\/latest\/dev\/api.html#local-development\">local deployments<\/a> of Pontoon at <code>http:\/\/localhost:8000\/graphql<\/code>. In the future we plan to <a href=\"https:\/\/bugzilla.mozilla.org\/show_bug.cgi?id=1407192\">enable it on production<\/a> as well.<\/p>\n<div style=\"width: 960px;\" class=\"wp-video\"><!--[if lt IE 9]><script>document.createElement('video');<\/script><![endif]-->\n<video class=\"wp-video-shortcode\" id=\"video-1183-1\" width=\"960\" height=\"500\" preload=\"metadata\" controls=\"controls\"><source type=\"video\/webm\" src=\"https:\/\/blog.mozilla.org\/l10n\/files\/2017\/10\/Pontoon-API-GraphiQL.webm?_=1\" \/><a href=\"https:\/\/blog.mozilla.org\/l10n\/files\/2017\/10\/Pontoon-API-GraphiQL.webm\">https:\/\/blog.mozilla.org\/l10n\/files\/2017\/10\/Pontoon-API-GraphiQL.webm<\/a><\/video><\/div>\n<p>&nbsp;<\/p>\n<p>The end goal is to expose almost all data that Pontoon stores and processes: translations and suggestions, contributors&#8217; activity, notifications and others.\u00a0 Ultimately the API will also allow writing to the database and will become the back-end for the future versions of Pontoon. We&#8217;d like to keep the development of the API use-case-driven. If you&#8217;re interested in creating a report or an extension which pulls data from Pontoon please let us know about your use-case! We&#8217;d like to prioritize the upcoming features to best serve the needs of the community. Refer to the <a href=\"https:\/\/wiki.mozilla.org\/L10n:Pontoon\/API\">L10n:Pontoon\/API<\/a> wikipage for more information about the planning process.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>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 &hellip; <a class=\"go\" href=\"https:\/\/blog.mozilla.org\/l10n\/2017\/10\/10\/exposing-pontoon-data-through-api\/\">Read more<\/a><\/p>\n","protected":false},"author":104,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[286406],"tags":[],"_links":{"self":[{"href":"https:\/\/blog.mozilla.org\/l10n\/wp-json\/wp\/v2\/posts\/1183"}],"collection":[{"href":"https:\/\/blog.mozilla.org\/l10n\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blog.mozilla.org\/l10n\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blog.mozilla.org\/l10n\/wp-json\/wp\/v2\/users\/104"}],"replies":[{"embeddable":true,"href":"https:\/\/blog.mozilla.org\/l10n\/wp-json\/wp\/v2\/comments?post=1183"}],"version-history":[{"count":0,"href":"https:\/\/blog.mozilla.org\/l10n\/wp-json\/wp\/v2\/posts\/1183\/revisions"}],"wp:attachment":[{"href":"https:\/\/blog.mozilla.org\/l10n\/wp-json\/wp\/v2\/media?parent=1183"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.mozilla.org\/l10n\/wp-json\/wp\/v2\/categories?post=1183"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.mozilla.org\/l10n\/wp-json\/wp\/v2\/tags?post=1183"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}