Guides

🔥 Subscribe to our newsletter to be notified when a new guide becomes available.

Getting started

  1. 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.

  2. Connecting to the GraphQL server from a client

    The website can connect to the GraphQL server from any browser running JavaScript.

  3. Intro to the GraphiQL client

    Gato GraphQL provides the GraphiQL client to to interact with the GraphQL service.

  4. Intro to the Voyager client

    Gato GraphQL provides the GraphQL Voyager client to visualize the GraphQL schema interactively.

  5. 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

  1. Security

    Multiple mechanisms provided by Gato GraphQL to help protect your data.

  2. 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.

  3. 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.

  4. Predefined Persisted Queries

    Gato GraphQL ships with predefined Persisted queries, which tackle several admin tasks that are common to many WordPress sites.

  5. 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.

  6. 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.

  7. 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.

  8. 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.

  9. Schema namespacing

    Schema namespacing enables to avoid conflicts in the schema, by having all type names namespaced.

  10. 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.

  11. 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.

  12. Global Fields

    Global fields are fields that are accessible under every single type in the GraphQL schema (while being defined only once).

  13. 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.

  14. Multi-Field Directives

    Have directives applied to multiple fields (instead of only one), for performance and extended use cases.

  15. Returning different types on mutations

    Mutation fields can be configured to return either a payload object type, or directly the mutated entity.

  16. Field and directive-based versioning

    Version fields and directives independently from the schema.

  17. Proactive feedback

    Use the top-level entry 'extensions' to send data concerning deprecations and warnings in the response to the query.

  18. 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.

  19. Public/Private Schema

    Control the desired behavior when a user without access to some field or directive in the schema attempts to access it.

  20. HTTP Caching

    Because persisted queries can be accessed via GET, their response can be cached through standard HTTP caching.

  21. 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.

  22. 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.

  23. 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.

  24. Function Fields

    The GraphQL schema is provided with fields which expose functionalities commonly found in programming languages (such as PHP).

  25. Function Directives

    The GraphQL schema is provided with directives which expose functionalities commonly found in programming languages (such as PHP).

  26. HTTP Client

    The GraphQL schema is provided with global fields to execute HTTP requests against a webserver and fetch their response.

  27. 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

  1. Executing Queries and Mutations

    Examples of the two supported operations in the GraphQL server: queries and mutations.

  2. Posts

    Examples of queries to fetch and modify post data.

  3. Custom Posts

    Examples of queries to fetch custom post data.

  4. Blocks

    Examples of queries to fetch block data.

  5. Pages

    Examples of queries to fetch page data.

  6. Users

    Examples of queries to fetch user data and log the user in.

  7. Comments

    Examples of queries to fetch and add comments.

  8. Post Tags

    Examples of queries to fetch post tag data.

  9. Post Categories

    Examples of queries to fetch post category data.

  10. Custom Tags

    Examples of queries to fetch custom tag taxonomy data.

  11. Custom Categories

    Examples of queries to fetch custom category taxonomy data.

  12. Media

    Examples of queries to fetch and mutate media data.

  13. Meta Values

    Examples of queries to fetch meta data, and filter results by meta.

  14. Menus

    Examples of queries to fetch menu data.

  15. Settings

    Examples of queries to fetch settings from the 'wp_options' table.

  16. Directives

    Examples of directives provided via Gato GraphQL extensions.

Creating an API

  1. 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.

  2. 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.

  3. Creating a schema configuration

    A schema configuration is used to customize the schema for Custom Endpoints and Persisted Queries.

  4. 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.

  5. Defining access control

    We can manage who can access every field and directive in the schema through access control lists.

  6. 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

  1. 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.

  2. 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.

  3. Using nested mutations

    Nested mutations enable to perform mutations on a type other than the root type in GraphQL.

  4. 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.

  5. 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.

  6. 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.

  7. Executing multiple queries concurrently

    Multiple queries can be combined together, and executed as a single operation, reusing their state and their data.

  8. 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.

  9. 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.

  10. 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

  1. 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.

  2. Browsing, enabling and disabling modules

    All functionality in Gato GraphQL is provided through modules, and these can be enabled and disabled.

  3. 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.

  4. Defining the default schema configuration

    The default schema configuration is applied to Custom Endpoints and Persisted Queries, and selected via the Settings.

  5. Defining the schema configuration for the Internal GraphQL Server

    The Internal GraphQL Server always applies the Schema Configuration defined in its own Settings.

  6. 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.

  7. Allowing access to Custom Post Types

    Configuring an endpoint in Gato GraphQL to indicate what Custom Post Types can be accessed.

  8. 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.

  9. 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.

  10. 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.

  11. 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.

  12. 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.

  13. 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.

  14. Enabling and configuring the single endpoint

    The GraphQL single endpoint allows to execute queries against the GraphQL server with unrestrained access.

  15. Configuring custom endpoints

    Configuring the base URL for custom endpoints in Gato GraphQL.

  16. Configuring the GraphiQL client for the single endpoint

    Configuring the URL to access the single endpoint's GraphiQL client.

  17. Configuring the Voyager client for the single endpoint

    Configuring the URL to access the single endpoint's interactive schema client.

  18. 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.

  19. 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.

  20. Printing the Settings page with tabs or long format

    Organizing the Settings in a single long page, or via tabs.

  21. 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.

  22. Managing the plugin's setup data

    Enable/disable installing predefined custom endpoints and persisted queries

  23. Managing who can edit the schema

    With Schema Editing Access, we can enable to grant non-admin users access to create and manage endpoints.

  24. 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.

  25. Removing types from the schema

    Two ways to remove types from the schema, whether for all endpoints, or for specific endpoints.

  26. Removing fields and directives from the schema

    Using Access Control to remove elements from the GraphQL schema.

  27. 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).

  28. 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.

  29. 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.

  30. 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.

  31. 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.

  32. 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.

  33. Hiding Global Fields

    Gato GraphQL offers to not expose the global fields (when doing introspection).

  34. Disabling introspection

    Disabling introspection for the single endpoint or custom endpoints via Access Control.

  35. 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

  1. Schema extensions via introspection

    Custom metadata attached to schema elements can be queried via field 'extensions' when doing introspection.

  2. '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.

  3. '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.

  4. 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).

  5. 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

  1. Working with Custom Posts

    This is how to query custom post data from the GraphQL schema.

  2. Working with Custom Tags

    This is how to query tag data from the GraphQL schema.

  3. Working with Custom Categories

    This is how to query category data from the GraphQL schema.

  4. 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.

  5. Working with (Gutenberg) blocks

    This is how to query (Gutenberg) block data from the GraphQL schema.

  6. Handling mutation payloads

    This guide explains how to handle returning the payload object type in mutations.

  7. 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.

  8. 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

  1. 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?

  2. Explaining nested mutations

    Nested mutations enable applying a mutation to the result of another operation, whether a query or mutation.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

  7. 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?

  8. 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.

  9. Strategies for API hierarchies

    Applying different ideas to set-up a hierarchy for our API endpoints.

  10. 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.

  11. 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.

  12. 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.

  13. 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?

  14. 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?

  15. Cache control via persisted queries

    HTTP caching is a better solution than relying on client-side logic for caching the GraphQL response.

  16. Scripting capabilities via meta directives

    Where can applying a directive to modify the behavior of another directive prove useful.

Resources

  1. GraphQL best practices

    These are some of the most compelling guides out there on best practices in GraphQL.

  2. GraphQL clients

    This is a compilation and overview of some of the most popular clients to interact with GraphQL.