Use GraphQL queries to create pre-defined enpoints as in REST, obtaining the benefits from both APIs.
With REST, you create multiple endpoints, each returning a pre-defined set of data.
Advantages | Disadvantages |
---|---|
✅ It's simple | ❌ It's tedious to create all the endpoints |
✅ Accessed via GET or POST |
❌ A project may face bottlenecks waiting for endpoints to be ready |
✅ Can be cached on the server or CDN | ❌ Producing documentation is mandatory |
✅ It's secure: only intended data is exposed | ❌ It can be slow (mainly for mobile apps), since the application may need several requests to retrieve all the data |
With GraphQL, you provide any query to a single endpoint, which returns exactly the requested data.
Advantages | Disadvantages |
---|---|
✅ No under/over fetching of data | ❌ Accessed only via POST |
✅ It can be fast, since all data is retrieved in a single request | ❌ It can't be cached on the server or CDN, making it slower and more expensive than it could be |
✅ It enables rapid iteration of the project | ❌ It may require to reinvent the wheel, such as uploading files or caching |
✅ It can be self-documented | ❌ Must deal with additional complexities, such as the N+1 problem |
✅ It provides an editor for the query (GraphiQL) that simplifies the task |
Persisted queries combine these 2 approaches together:
- It uses GraphQL to create and resolve queries
- But instead of exposing a single endpoint, it exposes every pre-defined query under its own endpoint
Hence, we obtain multiple endpoints with predefined data, as in REST, but these are created using GraphQL, obtaining the advantages from each and avoiding their disadvantages:
Advantages | Disadvantages |
---|---|
✅ Accessed via GET or POST |
|
✅ Can be cached on the server or CDN | |
✅ It's secure: only intended data is exposed | |
✅ No under/over fetching of data | |
✅ It can be fast, since all data is retrieved in a single request | POST |
✅ It enables rapid iteration of the project | |
✅ It can be self-documented | |
✅ It provides an editor for the query (GraphiQL) that simplifies the task |
Clicking on the Persisted Queries link in the menu, it displays the list of all the created persisted queries:
A persisted query is a custom post type (CPT). To create a new persisted query, click on button "Add New GraphQL persisted query", which will open the WordPress editor:
The main input is the GraphiQL client, which comes with the Explorer by default. Clicking on the fields on the left side panel adds them to the query, and clicking on the "Run" button executes the query:
When the query is ready, publish it, and its permalink becomes its endpoint:
Appending ?view=source
to the permalink, it will show the persisted query and its configuration (as long as the user has access to it):
By default, the persisted query's endpoint has path /graphql-query/
, and this value is configurable through the Settings:
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 |
Video showing how to create a persisted query: https://vimeo.com/443790273