Guides
🔥 Subscribe to our newsletter to be notified when a new guide becomes available.
Getting started
Intro to GraphQL and Gato GraphQL
Welcome to the Gato GraphQL guides. Here you will find plenty of information on installing, configuring and using the Gato GraphQL plugin on your WordPress site.
Connecting to the GraphQL server from a client
The website can connect to the GraphQL server from any browser running JavaScript.
Intro to the GraphiQL client
Gato GraphQL provides the GraphiQL client to to interact with the GraphQL service.
Intro to the Voyager client
Gato GraphQL provides the GraphQL Voyager client to visualize the GraphQL schema interactively.
What is schema introspection
Schema introspection is GraphQL's mechanism to provide information about the schema, which is retrieved using the same GraphQL language.
Special features
Security
Multiple mechanisms provided by Gato GraphQL to help protect your data.
Custom Endpoints
Create and expose multiple custom GraphQL schemas under their own URL, and grant access to each of these endpoints to some specific target.
Persisted Queries
Persisted queries are normal GraphQL queries, however they are stored in the server and accessed under their own URL, thus emulating a REST endpoint.
Public, Private & Password-Protected Endpoints
In addition to creating and exposing public endpoints, we can also create private endpoints, and protect a public endpoint with a password.
Internal Endpoint for Blocks
An internal GraphQL endpoint is accessible within the wp-admin only, to allow developers to fetch data for their Gutenberg blocks.
API Hierarchy
An API may expose several endpoints which are somehow related to each other, and which may execute a similar query. Through the API Hierarchy we can define a structure for endpoints.
Endpoint Management
When creating a Custom Endpoint or Persisted Query, we can add a 'GraphQL endpoint category' to it, to organize all of our endpoints.
Schema namespacing
Schema namespacing enables to avoid conflicts in the schema, by having all type names namespaced.
Nested mutations
Nested mutations make the schema more logical and browsable, by enabling to perform mutations on any type, and not only on the root type.
Exposing “sensitive” data
The GraphQL schema must strike a balance between public and private data, as to avoid exposing private information in a public API.
Global Fields
Global fields are fields that are accessible under every single type in the GraphQL schema (while being defined only once).
Composable directives
A composable directive can augment another directive to modify its behavior or fill a gap. This removes the need to duplicate fields or directives just to change their input or return types, avoiding bloat.
Multi-Field Directives
Have directives applied to multiple fields (instead of only one), for performance and extended use cases.
Returning different types on mutations
Mutation fields can be configured to return either a payload object type, or directly the mutated entity.
Field and directive-based versioning
Version fields and directives independently from the schema.
Proactive feedback
Use the top-level entry 'extensions' to send data concerning deprecations and warnings in the response to the query.
Access Control
The GraphQL endpoint, which can return any piece of data accessible through the schema, could potentially allow malicious actors to retrieve private information. Hence, we must implement security measures to protect the data.
Public/Private Schema
Control the desired behavior when a user without access to some field or directive in the schema attempts to access it.
HTTP Caching
Because persisted queries can be accessed via GET, their response can be cached through standard HTTP caching.
Multiple Query Execution
Query batching enables the GraphQL server to execute multiple queries in a single request, but those queries are merely executed one after the other, independently from each other.
Field Deprecation via UI
Deprecation is standard GraphQL behavior, but is normally executed via code. Through Gato GraphQL's Field deprecation user interface, we can already deprecate fields, without the need to deploy any code.
Field to Input
With Field to Input, we can obtain the value of a field, manipulate it, and input it into another field, all within the same query.
Function Fields
The GraphQL schema is provided with fields which expose functionalities commonly found in programming languages (such as PHP).
Function Directives
The GraphQL schema is provided with directives which expose functionalities commonly found in programming languages (such as PHP).
HTTP Client
The GraphQL schema is provided with global fields to execute HTTP requests against a webserver and fetch their response.
Schema Editing Access
Grant non-admin users access to the GraphiQL and Interactive schema clients in the admin, and to access the different screens in Gato GraphQL.
Query examples
Executing Queries and Mutations
Examples of the two supported operations in the GraphQL server: queries and mutations.
Posts
Examples of queries to fetch and modify post data.
Custom Posts
Examples of queries to fetch custom post data.
Blocks
Examples of queries to fetch block data.
Pages
Examples of queries to fetch page data.
Users
Examples of queries to fetch user data and log the user in.
Comments
Examples of queries to fetch and add comments.
Post Tags
Examples of queries to fetch post tag data.
Post Categories
Examples of queries to fetch post category data.
Custom Tags
Examples of queries to fetch custom tag taxonomy data.
Custom Categories
Examples of queries to fetch custom category taxonomy data.
Media
Examples of queries to fetch and mutate media data.
Meta Values
Examples of queries to fetch meta data, and filter results by meta.
Menus
Examples of queries to fetch menu data.
Settings
Examples of queries to fetch settings from the 'wp_options' table.
Directives
Examples of directives provided via Gato GraphQL extensions.
Creating an API
Creating a custom endpoint
Gato GraphQL supports custom endpoints, to retrieve and post data for a custom schema (containing only a subset of the available types) and user validation rules, as to deal with the needs from different users and applications.
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.
Creating a schema configuration
A schema configuration is used to customize the schema for Custom Endpoints and Persisted Queries.
Creating an API hierarchy
Custom endpoints and persisted queries can be organized into a hierarchy. This is achieved when they declare a parent, in which case their endpoint paths will extend the parent's endpoint path.
Defining access control
We can manage who can access every field and directive in the schema through access control lists.
Adding HTTP caching
When queries are executed against the GraphQL server using GET, the GraphQL response can be cached on the client-side, or on intermediate stages between the client and the server, by relying on standard HTTP caching.
Configuring the schema
Namespacing the schema
Namespacing the schema avoids naming conflicts, which happens when different owners (eg: different teams in the company, or among 3rd party plugins) use the same name for a type or interface.
Adding custom headers to the GraphQL response (CORS)
We can add custom headers to the GraphQL response. This is particularly useful to set the 'Access-Control-Allow-Origin' header to avoid issues with CORS.
Using nested mutations
Nested mutations enable to perform mutations on a type other than the root type in GraphQL.
Querying “sensitive” data fields
The GraphQL schema must strike a balance between public and private fields, as to avoid exposing private information in a public API.
Querying 'self' fields
We can modify the shape of the response (to emulate the same response from another GraphQL server, or from the REST API) via the 'self' field.
Making the API public or private
When access to some a field or directive is denied through access control, there are two ways for the API to behave: public mode or private mode.
Executing multiple queries concurrently
Multiple queries can be combined together, and executed as a single operation, reusing their state and their data.
Deprecating fields
Versioning a GraphQL schema involves deprecating fields, i.e. telling the user that the field should not be used anymore, and what other field to replace it with.
Using composable directives
Composable directives modify the behavior of their nested directives, unlocking the possibility to iterate array values in fields and applying a directive to each value.
Using "field to input"
With Field to Input, we can obtain the value of a field, manipulate it, and input it into another field, all within the same query.
Configuring the plugin
Installing and upgrading a bundle or extension
After purchasing a bundle or extension, you will have access to the corresponding plugin file. Here is how to install and activate it.
Browsing, enabling and disabling modules
All functionality in Gato GraphQL is provided through modules, and these can be enabled and disabled.
Configuring the plugin via the Settings page, environment variables, wp-config, and hooks
Explanation of the different ways to configure the options in Gato GraphQL.
Defining the default schema configuration
The default schema configuration is applied to Custom Endpoints and Persisted Queries, and selected via the Settings.
Defining the schema configuration for the Internal GraphQL Server
The Internal GraphQL Server always applies the Schema Configuration defined in its own Settings.
Modifying the default and max number of results
The are several fields which return a list of results, and we can limit how many results to fetch by providing the 'limit' field argument in the query.
Allowing access to Custom Post Types
Configuring an endpoint in Gato GraphQL to indicate what Custom Post Types can be accessed.
Resolving CustomPostUnion to a single type
If there is only one type added to 'CustomPostUnion' (eg: only 'Post'), we can then have the fields that resolve to 'CustomPostUnion' be resolved to that unique type instead.
Adding a custom tag taxonomy to the schema
Custom Post Types defined by any theme or plugin can have their own tag taxonomy associated to them, and added to the GraphQL schema.
Adding a custom category taxonomy to the schema
Custom Post Types defined by any theme or plugin can have their own category taxonomy associated to them, and added to the GraphQL schema.
Defining the allow/denylist for meta values
We can retrieve meta values for custom posts, users, comments, and taxonomies (tags and categories), by querying fields 'metaValue' and 'metaValues' from the corresponding type.
Returning a payload object or the mutated entity for mutations
We can configure mutation fields to return either a payload object type, or directly the mutated entity.
Defining the Setting's allowed entries
Configuring the list of entries that can be queried from the wp_options table in WordPress, via the optionValue fields added to the GraphQL schema.
Enabling and configuring the single endpoint
The GraphQL single endpoint allows to execute queries against the GraphQL server with unrestrained access.
Configuring custom endpoints
Configuring the base URL for custom endpoints in Gato GraphQL.
Configuring the GraphiQL client for the single endpoint
Configuring the URL to access the single endpoint's GraphiQL client.
Configuring the Voyager client for the single endpoint
Configuring the URL to access the single endpoint's interactive schema client.
Adding a description to the API
Using the excerpt field to provide a description for the different Custom Post Type entities in the Gato GraphQL plugin.
Displaying the plugin's new features
Immediately after updating the plugin, an admin notice will display a link to read the release notes for the new version.
Printing the Settings page with tabs or long format
Organizing the Settings in a single long page, or via tabs.
Creating Custom Internal Endpoints for Blocks
Developers can create their own pre-defined internal endpoints (to feed data to their application or blocks), as to apply a specific configuration.
Managing who can edit the schema
With Schema Editing Access, we can enable to grant non-admin users access to create and manage endpoints.
Enabling granular public or private mode
When editing an Access Control List, we can select individually on fields and directives if they are public or private.
Removing types from the schema
Two ways to remove types from the schema, whether for all endpoints, or for specific endpoints.
Removing fields and directives from the schema
Using Access Control to remove elements from the GraphQL schema.
Disabling mutations
There are two ways to disable mutations in the GraphQL schema, depending if it must be done for all endpoints or just for some specific one(s).
Restricting access by user login state, role or capability
Within Access Control, we can validate that the user has access to the selected schema elements (operations, fields and directives) using the standard WordPress access control functionality.
Restricting access by visitor IP
Within Access Control, we can use rule 'Visitor IP' to grant access to the selected schema elements (operations, fields and directives) based on the visitor coming from a list of allowed IP addresses.
Setting the default cache control max-age
In the settings for module 'Cache Control', there is option 'Default max-age', to define the default 'max-age' value for all fields and directives.
Configuring what environment variables and PHP constants can be queried
Configuring the list of allowed environment variables and PHP constants that can be queried via global field '_env' of the GraphQL schema.
Configuring what URLs can be HTTP-requested
Configuring the list of URLs that can be queried via the HTTP client fields added to the GraphQL schema.
Hiding Global Fields
Gato GraphQL offers to not expose the global fields (when doing introspection).
Disabling introspection
Disabling introspection for the single endpoint or custom endpoints via Access Control.
Enabling low-level editing of persisted queries
All directives to be applied to the schema become available in the GraphiQL editor when editing persisted queries.
Schema augmentation
Schema extensions via introspection
Custom metadata attached to schema elements can be queried via field 'extensions' when doing introspection.
'oneOf' Input Object
The oneOf input object is a particular type of input object, where exactly one of the input fields must be provided as input, or otherwise the server returns a validation error. This behavior introduces polymorphism for inputs in GraphQL, allowing us to design neater schemas.
'Enum String' types
Gato GraphQL implements a custom 'Enum String' type, which is a String type that can only receive a value from a pre-defined set, similar to an Enum.
Dynamic variables
Thanks to custom directives, the GraphQL server supports dynamic variables, where a dynamic variable has its value obtained when resolving the query in the server (whereas a static variable has its value provided by the client).
Output extensions
Gato GraphQL's 'Proactive Feedback' feature extends the response of the GraphQL API to offer additional information: Deprecations and Warnings.
Interacting with the GraphQL API
Working with Custom Posts
This is how to query custom post data from the GraphQL schema.
Working with Custom Tags
This is how to query tag data from the GraphQL schema.
Working with Custom Categories
This is how to query category data from the GraphQL schema.
Working with Meta Values
This is how to query meta data for custom posts, users, comments, and taxonomies (tags and categories) from the GraphQL schema.
Working with (Gutenberg) blocks
This is how to query (Gutenberg) block data from the GraphQL schema.
Handling mutation payloads
This guide explains how to handle returning the payload object type in mutations.
Security: Avoid exposing credentials used in the query
Unless our GraphQL API is not publicly exposed, we must be careful for the GraphQL query to not expose private data.
Changing the path to where a field is printed in the response
Is it possible to tell the GraphQL server to flatten the shape of the response? And, if so, how to do it?
Concepts, Ideas, Strategies
Fetching dynamically-structured data
In WordPress, we can fetch nested levels of data (i.e. entities which contain children items of the same type). How do we deal with this situation in GraphQL?
Explaining nested mutations
Nested mutations enable applying a mutation to the result of another operation, whether a query or mutation.
Namespacing the schema to avoid conflicts
Namespacing in GraphQL helps avoid naming collisions on the GraphQL schema, happening when two types, fields or directives have the same name.
Designing the application to work with different GraphQL servers
A GraphQL query acts an interface between the client and the server, allowing us to seamlessly swap one GraphQL server with another one.
Use cases for multiple custom endpoints
When it makes sense to expose multiple custom endpoints (instead of the single endpoint) in GraphQL, with each of these endpoints presenting a customized schema.
Evolving the schema via field versioning
When a change introduced to the GraphQL schema is a breaking one, we need to make sure we are not introducing bugs or unexpected behavior in the application.
Use cases for versioning fields and directives
We must know in advance that a field or directive has two or more versions to choose from, and we must know what those version numbers are. How should the GraphQL API inform the users?
Strategies for versioning fields and directives
Gato GraphQL allows fields and directives to receive argument 'versionConstraint', to choose what specific version of the field or directive to use.
Strategies for API hierarchies
Applying different ideas to set-up a hierarchy for our API endpoints.
How the plugin maps the WordPress data model into the GraphQL schema
This is how Gato GraphQL has mapped the WordPress data model into a corresponding GraphQL schema.
Similarities between WordPress hooks and GraphQL directives
A GraphQL directive is similar to a WordPress hook, in that it is a function that modifies the value of a field, thus augmenting some other functionality.
Mapping the GraphQL Schema for your WordPress site, theme or plugin
Strategies for producing the GraphQL schema from an existing WordPress application's data model.
Comparing field arguments and directives
When should we use field arguments and when query-side directives? Is there any difference between the two methods, or any situation when one option is better than the other?
Authorization via access control
When accessing the application via GraphQL, we must validate if the user has access to the requested elements from the schema. Should the authorization logic be coded within the GraphQL layer?
Cache control via persisted queries
HTTP caching is a better solution than relying on client-side logic for caching the GraphQL response.
Scripting capabilities via meta directives
Where can applying a directive to modify the behavior of another directive prove useful.