GraphQL API

Pontoon exposes some of its data via a public API endpoint.

The API is GraphQL-based and available at /graphql. The endpoint is exempt from CSP and CSRF validation so that is can be accessed by third-party code with ease.

Production Deployments

When run in production (DEV is False) the API returns application/json responses to GET and POST requests. In case of GET requests, any whitespace in the query must be escaped.

An example GET requests may look like this:

$ curl --globoff https://example.com/graphql?query={projects{name}}

An example POST requests may look like this:

$ curl -X POST -d "query={ projects { name } }" https://example.com/graphql

Local Development

In a local development setup (DEV is True) the endpoint has two modes of operation: a JSON one and an HTML one.

When a request is sent, without any headers, with Accept: application/json or if it explicitly contains a raw query argument, the endpoint will behave like a production one, returning JSON responses.

The following query in the CLI will return a JSON response:

$ curl --globoff http://localhost:8000/graphql?query={projects{name}}

If however a request is sent with Accept: text/html such as is the case when accessing the endpoint in a browser, a GUI query editor and explorer, GraphiQL, will be served:

http://localhost:8000/graphql?query={projects{name}}

To preview the JSON response in the browser, pass in the raw query argument:

http://localhost:8000/graphql?query={projects{name}}&raw

Query IDE

The GraphiQL query IDE is available at http://localhost:8000/graphql when running Pontoon locally and the URL is accessed with the Accept: text/html header, e.g. using a browser.

It offers a query editor with:

  • syntax highlighting,
  • field and arguments autocomplete,
  • real-time error reporting,
  • results folding,
  • autogenerated docs on shapes and their fields,
  • introspection via the __debug.