GraphQL¶
GraphQL is a query language for the API.
The GraphQL implementation for eZ Platform is located in ezsystems/ezplatform-graphql.
Setup¶
To use GraphQL, you need to generate the domain schema:
1 2 | |
This produces YAML files located in app/config/graphql/ezplatform.
They contain information about the domain objects and the fields
you can query and operate on.
Note
When you modify Content Types in your installation, you need to regenerate the schema using the command above.
Schema generation limitations¶
GraphQL schema cannot be generated for names that do not follow the GraphQL specification, for example names that start with a digit.
This concerns image variations, Content Types, Content Type groups, and Field definition identifiers.
It is recommended to rename the relevant identifiers. Failure to generate schema is registered in logs.
To find identifiers that are not included in the schema, look for "Skipped schema generation" log messages, for example:
Skipped schema generation for Image Variation.
Domain schema¶
GraphQL for eZ Platform is based on the Content Types, Content Type groups, and Content items defined in the Repository.
For each Content Type the schema exposes a singular and plural field, e.g. article and articles.
Use the singular field to query a single Content item, and the plural to get a whole Connection
(a list of Content items that supports pagination).
You can request additional content information such as the Section or Objects States,
available under the _info field.
You can also query Content Type and Content Type group information through the _info and _types fields.
Repository schema¶
The repository schema, accessed through _repository, exposes the eZ Platform Repository
in a manner similar to the Public PHP API.
The _repository field also enables you to query e.g. Object states configured for the Repository.
Custom schemas¶
You can also use your own custom schema.
Multiple repositories¶
GraphQL is SiteAccess-aware, but can have only one schema per installation. This means you cannot use GraphQL with multiple repositories.
Authentication¶
GraphQL for eZ Platform supports session-based authentication. You can get your session cookie by logging in through the interface or through a REST request.
Usage¶
You can access GraphQL with <yourdomain>/graphql.
GraphiQL client¶
The GraphiQL interactive client is included in the installation.
Access it through <yourdomain>/graphiql.
Here you can run your queries and preview the results in an easy-to-read format.
Note
Selected queries and mutations require administrator permission to be executed properly.
In such case, access the GraphiQL through <yourdomain>/admin/graphiql.
Reference¶
GraphiQL offers side-by-side reference based on your generated schema in the Docs pane.