Creating an API
Creating an APICreating a persisted query

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

Persisted query editor

Executing the persisted query

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 a persisted in the browser

Executing the persisted query in an application

Please follow the instructions on guide Connecting to the GraphQL server from a client.

Accessing all persisted queries

Clicking on "Persisted Queries" on the plugin's menu, it displays the list of all the created persisted queries:

Persisted Queries in the admin
Persisted Queries in the admin

Creating a new persisted query

Click on button "Add New GraphQL persisted query" to open the WordPress editor:

Creating a persisted query

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:

Persisted Query Endpoint Overview

By default, the persisted query's endpoint has path /graphql-query/, and this value is configurable through the Settings:

Persisted query Settings
Persisted query Settings

Query editor

The GraphiQL client in the editor is where to input the GraphQL persisted query:

The persisted query's GraphiQL client

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:

Composing a persisted query with the Explorer

Schema configuration

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):

Selecting the schema configuration

Private persisted queries

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.

Private Persisted Query

Password-protected persisted queries

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.

Password-protected Persisted Query

When first accessing a password-protected persisted query, we encounter a screen requesting the password:

Password-protected Persisted Query: First access

Once the password is provided and validated, only then the user will access the intended endpoint.

Making the persisted query dynamic via URL params

The value for each variable can be set via a URL param (with the variable name) when executing the persisted query. If option "Do URL params override variables?" is enabled, then the URL param will take priority. Otherwise, the value defined in the variables dictionary will take priority (if any).

For instance, in this query, the number of results is controlled via variable $limit, with a default value of 3:

Using variables in persisted query

When executing this persisted query, passing ?limit=5 will execute the query returning 5 results instead:

Overriding value for variables in persisted query

Creating a persisted query hierarchy

Please read the instructions on creating an API hierarchy.

Disabling the persisted query

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

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

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

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):

Persisted query's source


Configuration in the WordPress editor

These are the inputs in the body of the editor:

InputDescription
TitlePersisted query's title
GraphiQL clientEditor to write and execute the GraphQL query:
  • Write the query on the textarea
  • Declare variables inside the query, and declare their values on the variables input at the bottom
  • Click on the "Run" button to execute the query
  • Obtain the results on the input on the right side
  • Click on "Docs" to inspect the schema information
The Explorer (shown only if module GraphiQL Explorer is enabled) allows to click on the fields, and these are automatically added to the query
Schema configurationFrom the dropdown, select the schema configuration that applies to the persisted query, or one of these options:
  • "Default": the schema configuration is the one selected on the plugin's Settings
  • "None": the persisted query will be unconstrained
  • "Inherit from parent": Use the same schema configuration as the parent persisted query.
    This option is available when module API Hierarchy is enabled, and the persisted query has a parent query (selected on the Document settings)
OptionsCustomize the behavior of the persisted query:
  • Enabled?: If the persisted query is enabled.
    It's useful to disable a persisted query it's a parent query in an API hierarchy
  • Do URL params override variables?: Allow URL params to override the values for variables defined in the GraphiQL client
  • Inherit query from ancestor(s)?: Use the same query as the parent persisted query.
    This option is available when module API Hierarchy is enabled, and the persisted query has a parent query (selected on the Document settings)

These are the inputs in the Document settings:

InputDescription
PermalinkThe endpoint under which the persisted query will be available
CategoriesCan categorize the persisted query.
Eg: mobile, app, etc
ExcerptProvide a description for the persisted query.
This input is available when module Excerpt as Description is enabled
Page attributesSelect a parent persisted query.
This input is available when module API Hierarchy is enabled