What is GraphQL
How GraphQL Works
A GraphQL server defines and exposes a Schema of which consists of “Types” of data that should be accessible to the API. Each “Type” is either a simple Scalar type (string, integer, boolean, float, etc), or is an Object that has fields which can either be a Scalar value or another Object (that has fields that are either a Scalar or another object), all the way until the object resolves to a fields that are a simple Scalar value that doesn’t break down any further.
Each type and field has a “resolve” function tied to it, which is responsible for returning data in the shape the Schema has defined. The data the function returns can come from anywhere, such as a Database query, static arrays or objects defined on the server, remote API calls, etc. GraphQL doesn’t care where the data comes from, it just cares that the data matches the shape of the Schema that was defined.
A GraphQL query string can be sent via an HTTP request to a GraphQL endpoint, and the endpoint will parse the string and treat it as a “map” of functions, and will return data in the shape that it was requested.
Keep reading, there’s some examples below, or check out some of these resources to read more about GraphQL:
How WPGraphQL Works
WPGraphQL is a WordPress plugin built on the PHP implementation of the GraphQL spec, and adds a GraphQL API for WordPress sites.
WPGraphQL is a standard GraphQL server, with a Schema defined for the common “Types” of data that make up WordPress: Categories, Comments, MediaItems (attachments), Pages, Posts, Plugins, Tags, Themes and Users, with the ability to extend for Custom Post Types, Custom Taxonomies and any other custom data that a plugin or theme may want to expose to the GraphQL API.
These “Types” of data can be accessed via GraphQL Queries from any system or language that can make an HTTP request, or from within WordPress via a function call.
When a Query is sent to the GraphQL endpoint, WPGraphQL parses the query and treats it as a map to functions. The functions are called and the results are compiled and returned in the same shape as the query.
Installing and Setting up the WPGraphQL WordPress Plugin
Note: as of writing this, the plugin is in very early stages, so there could be breaking changes before it’s considered production ready.
To start using WPGraphQL, download the plugin from Github and activate the plugin like you would activate any other WordPress plugin.
Once active, you’ll need to flush your permalinks.
Next, you’ll want to use GraphiQL, which is a GraphQL IDE / schema explorer.
I highly recommend using the GraphiQL desktop app found here: https://github.com/skevy/graphiql-app, but there’s also a Chrome Extension, and likely other variations you can find. (WPGraphQL will have GraphiQL built in or available as an extension plugin soon, so you can use GraphiQL in WordPress).
Exploring the Schema
Once the plugin is active and you’ve got the GraphiQL IDE open, point GraphiQL to “yoursite.com/graphql”
You should now be able to explore the Schema, by using the “Documentation Explorer” at the top right.
At the root of the Schema is a “
rootQuery". Clicking on that will show what "queries" can be ran against the API. Clicking into each query will show the fields that can be requested back, and the arguments that can be passed to the field.
Testing Some Queries
Over on the left side of the GraphiQL tool you can start typing out queries and it will provide “typeahead” hints to help you so you know what queries you can write and the fields that are available on each query. The response of the query will be the same shape that the request defined.