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-contentand execute it passing the ID of the post:?post=1/graphql-query/post-content/esto translate the content of the post to Spanish- Others
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 Connecting to the GraphQL server from a client.
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.
The link to the endpoint (and to the source) is shown on the "Persisted Query Endpoint Overview" sidebar panel:
By default, the persisted query's endpoint has path /graphql-query/, and this value is configurable through the Settings:
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):
Private persisted queries permalink
By setting the status of the Persisted Query as private, the endpoint can only be accessed by the admin user. This prevents our data from being unintentionally shared with users who should not have access to the data.
For instance, we can create private Persisted Queries that help manage the application, such as retrieving data to create reports with our metrics.
Password-protected persisted queries permalink
If we create a Persisted Query for a specific client, we can assign a password to it, to provide an additional level of security that only that client will access the endpoint.
When first accessing a password-protected persisted query, we encounter a screen requesting the password:
Once the password is provided and validated, only then the user will access the intended endpoint.
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.
Testing the persisted query before publishing online permalink
A persisted query with status draft or pending is available to the schema editor users only.
Then, we can create a persisted query, assign a Schema Configuration, publish it as draft or pending, and test it (eg: checking that its Access Control rules are appropriate).
Once approved, only then we set its status as publish, making the persisted query available to everyone.
Viewing the source permalink
Appending ?view=source to the endpoint, it will show the persisted query's configuration (as long as the user is logged-in and the user role 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 |