there? Yeah. So, Graph QL is the word graph. QL stands for graph query language. So it’s a, it’s a language to specify what types of data you want from an API and get a response matching the type of data that you asked for. So

Yeah. So they basically in simple in simple terms, it’s a way to get data out of a system. There’s obviously lots of ways to get data out of systems, though. And so what are some unique things with Graph QL? It gives you one entry point into this graph of data, if you will. And so whatever, whatever your system can expose, it describes that in a schema, what’s called the schema. So you describe what’s possible to be asked for.

So when we talk about WordPress, like WordPress has posts, like blog posts, it has pages, it has users, it has media items, like images and things like that. So describes these types of data in a schema. And then the user gets to make Graph QL queries, graph query language queries, to specify what from that schema, they want to ask for some different API’s like RESTful API is would be like resource, an endpoint per resource, like you would have a specific endpoint to get posts a specific endpoint to get pages a specific endpoint to get images.

Graph QL gives you one entry point one endpoint. And then the user says, Okay, I want posts and pages and users maybe all all at once, but I want just posts and on posts, I want just these three fields. Yeah, so it gives the control to the, to the consumer.

Yeah, yeah. I mean, there, there was some inspiration, the creators of Graph QL. So Facebook, engineers at Facebook created Graph QL, to solve some problems that we’re actually having with using restful API’s with the mobile application for Facebook. And so there is some inspiration from sequel, rest API’s, give you data in JSON over endpoints. So it’s resources, and you’ll get a payload. But you as the consumer have very little control in a REST API over what you get. There are, that’s not universally true. There are rest API’s that allow you to send arguments to specify what fields you want. But in general, the server has most of the control and the consumers just, hey, please let me have something and you just wait for what you get.

Yeah, that’ll that’ll, that’s probably just regardless of API technology that can that can be a problem in Graph QL. To write like, you can Graph QL itself is the transport layer, the mechanism that says, here’s what users are allowed to ask for. And here’s how the server will respond. You can design Graph QL, API’s to expose data you shouldn’t expose. But and same with rest. You can you can expose REST endpoints that have too much data. So that that’s probably an implementation detail graph. QL itself is not going to necessarily prevent From exposing things,

Yeah. Could could be a little bit about. So so one thing with Graph QL, very much like any REST API to write, like, a lot of it is up to up to the implementers on how they implement the technology. Sure. So Graph QL. doesn’t, doesn’t the technology itself doesn’t specify how you design your schema. So you can have a schema that is as simple as one single field, like a hello field that returns the word world, right? So you have a Hello World API, that can be your entire graph. QL API, right? Probably not a useful one.

But But Graph QL itself says like, if you’re going to expose this, you have to expose it in a standard way, you have to say what type of data your field is going to return. In that case, you’d have to specify it’s going to be a string. And then users always know anytime I asked for that field, I’m going to get a string back. Right? So it’s a contract between the server and the client. That said, it obviously can get more complicated than that. So there’s a specification in the Graph QL ecosystem called the relay specification.

And this, this is a kind of a standard opinion on how to design schemas. So if you’ve ever messed with a graph, QL schema and seen terms like edges and nodes, I’m not sure. Okay. The API you worked with had that terminology? I don’t remember. So if you were frustrated, part of it could have been maybe lack of familiarity lack of documentation, there was definitely been poor API design to Yeah.

yeah. Yeah, like one one example for like W in WP graph kill if we think like WordPress is used for a lot of websites, right. And I, and if you break down like, yeah, 43% of the way, literally dozens. But if you consider like, I don’t know, a homepage of a website, you would have probably, you’d have some general data about the website, like the title of the website and the logo. And then you typically are going to have some sort of navigation menu with like a list of navigation menu items.

And then you probably have, let’s say, it’s a blog again. So the homepage would have the menu, the logo, the title of the site, then a list of blog posts, the blog is going to have the title, the blog, the date, the description, a link to the individual posts, maybe an image, and then the author’s name, and maybe avatar or something. Sure. It’s like we’re talking, there’s a dozen resources here, right, you’re talking you got settings of the site, you got menus, menu items, posts, post images connected to the posts, and the user connected to the post.

So you can do that all in one graph. QL request. So you can you can say I want the menu with the menu items, I want the posts with their author and their featured images, and the author’s avatar, which is even another resource. So you do that all in one single WP Graph QL request, where with rest, you’d have to do like, I don’t know, probably 100 different network requests

Yeah, it puts a Yeah, it puts more like control in the consumers hands to specify exactly what they want. And in response, in turn, it usually leads to speed improvements. Because with rest, if you only need, let’s say, ID and the title of a for list of posts, and the posts has 400 fields on it, in a REST API, you might be waiting for 400 fields to be downloaded, when all you care about is the two that you need.

So Graph QL, you specify, Hey, I just want the ID and the title. And then the server only has to process that get it from the database, you know, send it to you. So the request response time alone is fast. And then any processing on the server is going to be faster to

Yeah, I was gonna say 111 thing I love too about it is with the REST API. If something breaks down the road in your application that’s consuming your REST API. It’s hard to know what changed. Because like, when you’re looking at your code, like let’s say jump into code base, maybe somebody else authored, and you see, oh, shoot, this thing is broken over here. I see they were getting this resource from this endpoint, you have to go figure out how that endpoint used to behave and how it behaves today.

With Graph QL, you the whoever wrote the code wrote a query that is very explicit, they said, I want the posts, I want the ID and the title. If for some reason the server isn’t sending the title anymore, you at least know what the original developer, maybe it was even you two weeks ago, but you know, what the original developer wanted from the API. So it takes a little bit of guesswork, you can start troubleshooting immediately. Oh, one of these two fields they asked for isn’t behaving the way it used to.

Now I can troubleshoot that, versus Oh, they were asking for posts, posts and 400 fields, one of them isn’t working. Which one was it? Why is it different? You know, what changed? So it’s the implicit rester, a lot of API’s, like rest are implicit because you just say, I want this resource server, give me whatever you have graph. QL is like, tell me exactly what you want.

any type, whatever you say? Any? Yeah,

yeah, I mean, so Well, well, let’s talk about it in terms of WordPress again. So if you’ve installed WP Graph QL, which is a free open source plugin for WordPress, you install this into your Graph QL or into your WordPress, you have a Graph QL endpoint, anything that can make a network request to that endpoint can talk with API. So you can go in your browser, type in your site.com/graph QL. And you you’ll get data, right and then you can type queries into the query string of your browser event.

And specified data like hey, I want just post their ID and their title. And in your browser, you can get data back, you could do a curl request in your terminal to a Graph QL API and get data back. JavaScript clients are probably the more the most common consumer of Graph QL API’s provide JavaScript and like native mobile applications. So if you are going to be building JavaScript website, or application or whatever and wants to communicate with the Graph QL API, you can do it with standard fetch API’s write that can make a network request.

There are libraries though, that help make the communication to Graph QL API easier. So the popular one is called Apollo Apollo client, and you can use this in JavaScript applications, it will make it a little bit easier to communicate to the server, it’ll do the fetch for you, it’ll set the headers for you. But then add also does caching for you. It’s smart enough to know that you already have that data. And we’ll skip the network requests a second time.

So yeah, there’s there’s a lot of libraries that try and make things easier to use Graph QL API’s. But anything that can make a network request should be able to work with Graph QL API,

Most API’s are that I know of are going to return JSON, it’s pretty much a standard graph. QL doesn’t enforce it. You can return whatever you want. It’s pretty standardized that it’s going to be JSON, though.

Yeah, I saw I started the project almost five years ago, it’s Thanksgiving week of 27, or 2016. is when I started the project. I was working at newspaper at the time, and we we had like a network of 100, or something sites across the US. And at the time, 30 or so we’re on WordPress. And we did a lot of content syndication. So one newspaper would publish breaking news or whatever. And we would need to syndicate that article to other newspapers across the web.

Yeah, yeah. So graph. QL has three, three root interactions you can do, you can do queries, which is the most common one, you can ask for data, ie do mutations, which is write data back. And it works in a very similar way, the schema will be defined what mutations are possible, like in WordPress, it’d be like create post, update, post, delete post, yeah, things like that. And, yeah, so you can create mutations and queries.

So mutations typically change something in the site, like create data, or update data, or any data queries typically just return data, they don’t usually write data. And then there’s a third thing called subscriptions, which is very unique. You can subscribe to data. WP Graph QL doesn’t support this yet. But some Graph QL API’s do. And so subscriptions allow you to say you can subscribe to an event in the system. And then you can specify what data you care about when that event happens.

And then you’ll get you’ll get a payload of data typically, through a WebSocket connection, whenever that event occurs. So you can, you can subscribe, like in WordPress, when we support this, for example, you’ll have, you’ll be able to subscribe to something like create post, right? Anytime a post is created you you the consumer will be able to specify that when a post is created. You want the ID, the title and maybe the author of the post, right? And if a post is created, you’ll get a payload with that data.

Hit the transport, how it happens is up to the API. It’s pretty standard that WebSockets transport subscriptions. You could do something like web hooks or whatever else you want.

So it’s very similar tip, typical implementation is going to be WebSockets. So it can be real time, basically. But yeah, the actual transport of it doesn’t matter. The, what does matter is that the consumer can specify what event they care about and what data down to the field. They care about when that event happens. And so I can subscribe to different fields than you for the same event and will we would get individualized payloads. Sure, yeah.

Yeah, um, yeah, so. So one of the one of the common themes in restful API’s is that you’re simultaneous simultaneously, over fetching and under fetching at the same time. So if you need data, we talked about like having to do nested resources. If you need, like my example, you need a blog, post author and the images, right. If I’m using REST API, I’m going to hit the posts endpoint to get a list of posts. That’s going to give me ideas of the author.

So I have to go collect those IDs, and then make round trip requests to the author endpoint, or the user endpoint, whatever it is, and then get the user and then I’m gonna have to make subsequent request to get the avatar for the user. And then also, for my posts, I’m gonna have to make a request to get the images, right to the media and point, because I’m just going to get IDs, like the rest resource is going to give me the post data, but then IDs have any connected resources.

And then I as the client have to do these round trips. So just to get a list of 10 posts, with one image each and an author each, I’m going to have to make what is that 31 requests or something, I’m going to get one request for to get my 10 posts 10 requests to get my 10 images, 10 requests to get my 10 authors 10 request to get the avatars of authors. So I just made 31 network request to get a list of 10 posts with. And then if I want 100 posts, now making 301 requests, it solves that because I can write one query to say I want 100 posts are 10 posts.

And on each post, I went the ID, the title, the date, the author, the author’s name, the author’s avatar, the posts featured image, and the URL and the caption, or whatever. Each time I asked for the posts, I’m going to be getting all the fields the post has, if all I needed was the ID, the title and the date, I’m getting a lot more stuff than I asked for or, or that I write. So I have to wait, I have to wait for that. Even though I don’t need it, I have to wait for it before I can even make my round trip to get the author.

And then I have to wait for the whole author, which is going to have probably a lot of stuff I don’t care for if I just need the name and Avatar. But I have to wait for the whole payload for the author just to get the ID of the Avatar. And then I have to go ask for them.

yeah, so So the WordPress does allow you to do what’s called embed in the REST API, but then you get entire resources, right. And so again, you’re even if you do that, you’re still over fetching. And you have to pay the price to wait for all of that data to download and all the data to process so. And then if you want to do go a step further, that gets really difficult, like if you wanted, if you want to listen 10 posts and the author, but also the author’s two most popular posts to put in their bio, for example, like, Wait, if the REST API is saying, Oh, I’m just gonna include everything where does it stop, right?

Because if you’re gonna say, Oh, we can include the related authors or you know, related authors to this post. Then also we Want to include the posts that this author has? Written? You know, so the Graph QL API allows the client to specify those relationships and then stop where they want it to. Because and so, so yeah, you can, you can ask for stuff like the most recent list that the, the most recent posts, author is done, the popular post author’s done, like, there can be connections from the often in the graph to post but different ways, right?

So can have popular posts a query, you can have recent post. So like the REST API, it’s either gonna, it’s either going to punish the clients that don’t need all this information to benefit the clients that do need it all. Yeah, what’s the level of

Yeah, it’s it. That’s gonna depend as on so many variables. Yeah. Ultimately, we need to do a Graph QL request, you’re just basically mapping to a bunch of functions, right, that go and do something. So it all depends on how that’s behaving. But the fact the the fastest, the fastest API, regardless of graph, QL arrest is going to be the one that’s not hitting your server at all right? If it’s cached, sure, right. So there, there’s a typically in REST API is a user will make a GET request to get data.

So typically, a REST API is gonna gonna just give you the resource, give me IDs to relationships, and then that individual resource can be cached Graph QL, since you specified down to the field of what you want, Graph QL can track the dependencies that are in that response, and invalidate the cache based on anything that was in that response. So if you query for list of posts, then the authors and the images that specific requests can be invalidated when post authors or images are changed on the server.

Right so We can still invalidate that cache, because we know all of the resources that are included in it. Not every Graph QL servers can be set up to be cached like that. There’s tooling in the WordPress space we’re working on, specifically around around this. But the concept is, yeah, you you build your application to specify what you need in your application.

The server is going to track those requests, figure out what data is important to those requests, and then stack the corresponding events in WordPress to say, oh, we should invalidate this cache because that thing just changed. Typically, any API, you’re gonna want that layer of cache, though, I would say it’s probably that it’s a trickier problem in Graph QL. To cache there are like startups that are trying to solve this generally.

So like graph CDN, for example. There’s a startup that you can put their CDN in front of your Graph QL API, and it’s basically a proxy for your API, and it caches responses there. So then your client application is always getting data from a CDN instead of talking to your server.

that’s kind of the trend we’re seeing with graph. QL. Right is like, at that point, it shouldn’t matter if you are on a $5 box, right? Because most of the requests are going to be hitting a cache summer, and your servers not really going to end up seeing that much traffic. Obviously, you’d still have any uncashed stuff like if you had, like, for example, the newspaper worked at, we had 8000 authors on one of the newspapers, right. So like, we have to, we have to support those users.

Right, which is all uncashed stuff because they’re mutating data. They’re writing data. Right. So we add, we have more concerns with that user base than we did like the public facing users that are largely quitting and or corn cashable data. But uh, we so I would recommend no matter what API, you’re using, the cache layer, graph. CDM, I think is a cool, cool one. We like I’ve explored integration with that. That’s a from Max oibre.

He, I don’t know if you’re familiar with like styled components in the React ecosystem. He co created that. And so he’s behind DNS. He was working with Gatsby for a little bit, and worked at GitHub for a little bit.

Yeah, there, there are some like, I don’t know, the I don’t have like scientific results behind it. But there are some conventions in Graph QL that do help with like, the related resource issue. So I mentioned like to get 10 posts and REST API might end up doing 31 requests, right? We do the one to get the 10 posts, and then, you know, tend to get the author tend to get the avatar tend to get the, you know, whatever. The was lasting damage, or whatever. So that’s called like the n plus one problem, right?

You make one request, and then you have n requests to follow up to get the related resources with Graph QL since you make the one request, and you can specify those relationships There’s a pattern on the server called Data Loader that can help avoid that problem on the server as well. So if I, if I say I want from a Graph QL, request 10 posts with the author, the image and the author avatar, right, what’s going to happen, it’s called deferred resolution.

So as the server processes that will talk to the database and say, Hey, I need the 10 posts. But then instead of doing a for each loop, and say, for each 10 posts, give me the author. So that’d be get author one, and then get author two, it’ll say, get all 10 authors at once. So it’d be one request to get the 10 posts one request to get the 10 authors one request to get the 10 images, one request to get the 10 avatars. So you’d end up with four requests instead of 31.

pretty similar to that. So if you have a if you if you have post type, like houses, for example, you register post type houses, there’s three fields you have to specify to expose it to Graph QL. One is showing Graph QL, if you set that to true, and then you give it a graph, QL, single name and a Graph QL plural name, if you specify, if you specify those three fields, then you will get your your type exposed to the graph. And you’ll get a lot of things in your schema for that you’ll get a route entry point.

So you’d be able to query how a house individually by ID, you’d be able to query a list of houses, and you’d be able to filter it by, you know, various arguments. You’d also get mutations for that which due respect, whatever capabilities you define for your post type in WordPress. So when you registered type, you can specify what what user privileges are required to edit it created, deleted, things like that. And so WP graph kill will respect those, but it’ll add it to the schema, like, create house, update house, delete house mutations.

So you’ll get all of this stuff added to the graph, as well as connections to any taxonomies, you might have, like, let’s say you registered a custom taxonomy called neighborhoods, right? Or something like that. And you could have a house connected to a neighborhood, right? You’d be able to query both of those things in Graph QL. And find out what neighborhoods have which houses or which houses are connected to which neighborhood, things like that. So yeah, it’s just three fields on taxonomies are post types.

And then there’s a slew of helper API functions, you can call like register Graph QL field, if you want to register your own field to any type in the graph, you can do that. And then there’s a like register Graph QL connection. So if you were wanting to connect two types of data, like houses, neighborhoods, for example, I do that for you. If there’s a post type of taxonomy, like the code just does it. But maybe you had a custom database table, for example you were using.

And if you’re doing some with custom database tables, WordPress usually doesn’t know about it natively. So you could register connection yourself using the registered connection registered Graph QL connection, and then you could define how to connect something in WordPress to this other thing. It could even be remote data, right? Like you could, you could write a connection that actually goes and gets data from a third party REST API, for example.

And, and connects it back. Like, discuss comments, for example. Like if you wanted to have comments come from a third party instead of native WordPress, you can do that if you want to

yes or no. So Gutenberg is a loaded topic when it comes API’s. I wrote a I wrote a pretty lengthy blog post about this on It’s on WP graph kill that comes blog back in like March a so the so Gutenberg for folks that don’t know what Gutenberg is. It’s a block based Page Builder page editor that was brought into WordPress, like two years, two or three years.

Yeah. Yeah. As to Yeah. Anyways. So it’s this. It’s a, it’s a react based application that you kind of drag and drop your content as blocks. So you have like a paragraph block an image block a heading block. And you can compose your pages with these blocks. You can also build your own blocks or like, galleries or like whatever you’re doing. So you can build your own blocks. The problem when it comes to API’s in WordPress, so WordPress has the REST API built in and it has not built in well, it does have XML API as well built in.

And then there’s a tool called WP CLI. So like there’s a CLI interface. It’s not built in. But it’s essentially is natively simple. It’s a tool. Yeah, exactly. It’s a tool to interact over CLI. All of these API’s don’t know anything about Gutenberg blocks. Because Gutenberg blocks are fully JavaScript, and WordPress is PHP. And so when you register post types, or taxonomies, you register them in PHP, you describe what they are, and who can interact with them, right, I mentioned the capabilities.

For example, you can say, who’s allowed to write, edit, delete, a post type, Gutenberg blocks don’t exist, the server doesn’t really know much about Gutenberg blocks. And so for API’s, like the REST API for dumphy, graph, QL, for CLI for XML RPC API, don’t really know anything about blocks. And so it’s a little problematic. Currently, there are some solutions. So the blog post I mentioned, there’s one plugin called WP Graph QL, for Gutenberg. And when you install that, it gives you a settings page.

And you can basically index the Gutenberg schema. So what happens it loads up Gutenberg in an iframe, install JavaScript, and then it gets all the blocks that JavaScript knows about, send the sends that block list back down to the server saves it in database, and then it maps it to Graph QL. And then you can you can query the data that way. So I’ve been I’ve been working I’ve have issue on the Gutenberg GitHub repo from I think, 2017 Why the lack of a server registry in Gutenberg is problematic. And it’s issue 2751. If you’re curious.

But uh, I kind of I’ve kind of wrote a book about this, because as soon as I heard about Gutenberg, I was like, Oh, that’s cool. This is exciting. Like, I think Graph QL would actually pair very well with it. But the way it’s been architected to this point makes it very difficult for server APS to do meaningful stuff with it.

Yeah, definitely can, um, I did a I did a word workcamp. Talk about this word campus, like the WordPress conference. I did one. I think it was 2018 WordCamp. US I did a talk about using Graph QL to build Gutenberg blocks. So yeah, I was thinking about this the opposite way, like how can I query blocks, if you want to build a block and use graph kill on the client, as users are interacting with blocks, that’s definitely possible.

I have a talk on that I show how, in my case, you still use WP Graph QL in my example, but you can look it up on wordpress.tv Just search my name and you’ll find it it’s workcamp 2018. It’s like called Gutenberg, Graph QL and government or something. Um, let me

Yeah, um, it’s tough, I think there’s a lot of value, it could add to 40 plus percent of the internet, if it were a core problem with WordPress Core those like when typically when things get merged into WordPress, core innovation stops Gutenberg as like one exception. Like, there’s bugs with the REST API REST API, I think was merged in 2016. And there’s bugs that are yet to be fixed with it, right? Because once, once you say, hey, 43% of the web, you have this new shiny thing, it’s very difficult to change something for 43% of the web. Okay. Um,

as a plugin, like, we’re still able to iterate and, and fix mistakes we’ve made with and then you can opt into the version that works for you. Right. Um, so I’m only, I mean, I can obviously make breaking changes, but you can opt into the version that was working for you at any time, right? Without having to change everything in your system. So I think I think plugin makes sense, for a lot of reasons. One, for the speed of iteration, like, we can still ship features and sometimes make breaking changes, and you could opt into what version works for you, which is nice.

The other part is Graph QL is evolving at a different pace, and without regard to WordPress, right. So the Graph QL language and specification has changes coming as well, right? There’s features we want that don’t exist in Graph QL today, but hopefully, will soon. And we want to take advantage of those when they come. If Graph QL were merged into WordPress Core today, it would be the version of Graph QL. That is there today.

And so while the rest of the world moves on to Graph QL, to or whatever it might be, we’d be stuck with whatever it is today. Because, again, it’s very difficult to change 43% of the web. So I think there’s a lot of advantages of keeping it a plugin. And if it benefits your project, go install it, it’s a click away. If it doesn’t benefit your project, ignore it. Right. Like, it doesn’t have to be for everybody in the plugin

Yeah, it’s in wordpress.org. You can get it on GitHub, if you’re interested in like developing and contributing back. It’s on GitHub, if you use composer, which is like NPM. For php. It’s like a package dependency manager library. It’s on packagist.org, which is the posers version of NPM. So you can get it from composer you get it from wordpress.org, from your admin of your WordPress site, or GitHub.

Yeah, sure. So you can find me I’m on Twitter a lot at Jason ball je s when the HL also at WP Graph QL. So both of those handles on Twitter, lots of content about you know, Graph QL dad jokes, or fried pizza, you know, stuff like that. So yeah, you find me there. WP graph ql.com also has a website for the project. GitHub. GitHub is WP dash graph. QL is the organization you can find. We got the main plug in there.

And then there’s some extension plugins and whatnot up there as well. wordpress.org, you can find the plugin repository, you can find us on there as well. I do have a YouTube channel for WP Graph QL as well. Post just random stuff like here and there. It’s not like super frequent content, but cool. If it is something it’s beneficial, probably.