GraphQL

Gentics Mesh is also able to process GraphQL queries. You can use GraphQL to directly specify what fields should be retrieved and retrieve deeply nested data sets. Internally, Gentics Mesh will resolve your query and traverse your content graph to fetch only the data you specified.

The GraphQL API can thus be used to prepare a single request which returns all data needed to render a specific page.

Possible usecases are:

  • Loading multiple nodes using the webroot path.

  • Generating a custom navigation which only includes the information you need.

  • Invoking multiple search requests to find a set of specific nodes.

  • Resolve links within the content of a node.

  • Load users, roles, groups

  • Load tags, tag families, schema and microschema information

Live Examples

If you want to learn more about the GraphQL syntax take a look at the good documentation.

Loading current user

{ me { username, uuid } }

Loading basic fields of a node

{ node(path: "/yachts/pelorus") { fields { ... on vehicle { name description } } } }

Loading a node via uuid

{ node(uuid: "28f42d43a7604114b42d43a7602114da") { path } }

Loading referenced fields of a node

Nodes can be linked together in various way. One way is the regular parent-child relationship. Another way is by using node fields. The demo data contains vehicles which each is linked to a vehicle image. In order to present the vehicle we also need to retrieve the image path and other information.

{ node(path: "/yachts/pelorus") { fields { ... on vehicle { name description # The vehicleImage field is a node field # which points to a vehicle image node vehicleImage { path # We need to specify what kind of node we expect. # Otherwise we can't retrieve the image # binary field information. fields { ... on vehicleImage { image { width height fileSize mimeType dominantColor } } } } } } } }

Invoking a search query to find specific nodes

The search query is an escaped JSON object which represents the a regular Elasticsearch query.

{ # Search for all nodes which contain the string 'car' in the content nodes(query: "{\"query\":{\"query_string\":{\"query\":\"car\"}}}") { elements { uuid fields { ... on vehicle { slug } } } # Total amount of found results totalCount } }

Using pagination

Similar to the REST API a value based pagination system is implemented.

{ nodes(perPage: 2, page: 2) { elements { uuid } # Total amount of found elements totalCount # Total amount of found pages. Each page has a size of 2 pageCount # Size of the current page. The last page may only contain a few elements size # Current per page size perPage # Current page size size # Flag which indicates whether another page exists hasNextPage # Flag which indicates whether a previous page exists hasPreviousPage } }

Multilanguage support

The node will automatically be loaded in the language which matches up with the provided webroot path. A webroot path which points to an english node will yield the english content. Subsequent loading a node using the german path will yield the german content. It is important to node that Gentics Mesh tries to stick to a language as much as possible. Loading additional referenced nodes of an german node via either the children or a node field will return the german content if such content could be found. The fallback to the configured default language will be applied if no other matching content found be found. Null will be returned if this also fails.

It is possible to load a found node in a different language using the node field as shown in the example.

{ node(path: "/yachts/pelorus") { availableLanguages node(lang: "de") { language } } }

GraphiQL Browser

We have integrated the interactive GraphiQL[1] browser into Gentics Mesh so you can easily play with the API.

Try the example
Live Demo

Alternatively, you can download Gentics Mesh and test the API locally. Once authenticated you can access the interactive GraphiQL browser at /api/v1/:projectName/graphql/browser/ .

The GraphiQL browser currently does not support the release or version query parameter.

Limitations

  • At the moment, the GraphQL API can currently only be used for read-only operations. Modifying data with via mutations is currently not supported.

  • GraphQL queries are restricted to a specific project. It is not possible to query data across multiple projects.

  • GraphQL queries are restricted to a specific release. The scope of the release can be changed by adding the ?release query parameter.

1. GraphiQL is owned and developed by Facebook Inc. Usage is subject to the LICENSE AGREEMENT For GraphiQL software.