Creating a persisted query
A persisted query is a combination of GraphQL and REST APIs: it is a normal GraphQL query, published on the site and accessed under its own URL, similar to a REST endpoint.
For instance, we can expose data for a website through the following persisted queries:
/graphql-query/homepage-posts
/graphql-query/user-widget
/graphql-query/post-content
and execute it passing the ID of the post:?post=1
/graphql-query/post-content/es
to translate the content of the post to Spanish- Others
Accessing all persisted queries permalink
Clicking on "Persisted Queries" on the plugin's menu, it displays the list of all the created persisted queries:
Creating a new persisted query permalink
Click on button "Add New GraphQL persisted query" to open the WordPress editor:
Give it a title and make sure the permalink is the expected one, input the GraphQL query, select the schema configuration, and adjust the options. When ready, click on the Publish
button, and the permalink becomes the persisted query's endpoint:
Query editor permalink
The GraphiQL client in the editor is where to input the GraphQL persisted query:
The editor comes with the Explorer add-on, which allows to compose the query by clicking on the fields on the left side panel. Clicking on the "Run" button executes the query, to preview the response:
Schema configuration permalink
Defining who can access the fields requested in the persisted query is defined in the schema configuration.
So we must create a create a schema configuration, and then select it from the dropdown (or use none, or the default one):
Making the persisted query dynamic via URL params permalink
If the query makes use of variables, and option "Accept variables as URL params?" is enabled, then the values of the variables can be set via URL param when executing the persisted query.
For instance, in this query, the number of results is controlled via variable $limit
, with a default value of 3:
When executing this persisted query, passing ?limit=5
will execute the query returning 5 results instead:
Creating a persisted query hierarchy permalink
Please read the instructions on creating an API hierarchy.
Disabling the persisted query permalink
In the options, set "Enabled" to false
to disable the persisted query.
This feature can be useful when making the persisted query be part of an API hierarchy, to provide a common behavior to its child persisted queries, but without needing itself be executed.
Describing the persisted query permalink
Use the "Excerpt" field, from the Document settings panel, to give a description to the persisted query.
Find more information in guide Adding a description to the API.
Executing the persisted query permalink
Once the persisted query is published, we can execute it via its permalink.
The persisted query can be executed directly in the browser, since it is accessed via GET
, and we will obtain the requested data, in JSON format:
Executing the persisted query in an application permalink
Please follow the instructions on guide Executing queries against the GraphQL server.
Viewing the source permalink
Appending ?view=source
to the endpoint, it will show the persisted query's configuration (as long as the user has access to it):
Configuration in the WordPress editor permalink
These are the inputs in the body of the editor:
Input | Description |
---|---|
Title | Persisted query's title |
GraphiQL client | Editor to write and execute the GraphQL query:
GraphiQL Explorer is enabled) allows to click on the fields, and these are automatically added to the query |
Schema configuration | From the dropdown, select the schema configuration that applies to the persisted query, or one of these options:
|
Options | Customize the behavior of the persisted query:
|
These are the inputs in the Document settings:
Input | Description |
---|---|
Permalink | The endpoint under which the persisted query will be available |
Categories | Can categorize the persisted query. Eg: mobile , app , etc |
Excerpt | Provide a description for the persisted query. This input is available when module Excerpt as Description is enabled |
Page attributes | Select a parent persisted query. This input is available when module API Hierarchy is enabled |