Talking Drupal #357 - GraphQL

• What is GraphQL
• Common use cases
• Why GraphQL over JSON:Api
• How is it being used?
• How to use it with Drupal
• Is there a standard?
• How do you customize it?
• What resources do you recommend?

Transcript are generated with AI and lightly edited, therefore will not be 100% accurate.

John P  0:05  
This is talking Drupal, a weekly chat about web design and development from a group of people with one thing in common. We love Drupal. This is episode 357. Graph QL. welcome to Talking Drupal. Today we're talking about Graph QL. With Alexander Varwijk . Alexander is lead front end engineer at Open Social, who built his first website for his sports club. We'll learn more about that over 10 years ago using Drupal 7. He's a contributor to the Graph QL module, and the Graph QL. PHP library. He helps open socials to Drupal developers in the adoption of Graph QL and is leading the development of a new front end using Graph QL. React and rescript. And Alexander, welcome to the show. And thank you for joining us. (Thank you) I'm John Picozzi. And today my co hosts are joining us for his second time. Ryan Price. Ryan is a Solutions Architect at FFW, who is involved in Drupal who's been involved in the Drupal community since 2006. Ryan, welcome back.

Ryan P  1:22  
Hi, everyone. And hopefully I will be able to hang on this whole time I have a sick two year old at my house.

John P  1:28  
We

We'll will be okay. I think we we understand the trials and tribulations of having kids. So joining us as well. With an electrician in his house, Nic Laflin.

Nic L  1:43  
Yeah, this, this is reminiscent of early days, and I'd be recording from a Starbucks or something. So yeah, might be a little noisy on my side too. And since we've got somebody in the house, and if you're watching the video, I've got a mask on. So it might be a little muffled, but just trying to kind of stay safe. So I'm confused.

John P  1:58  
So electricity is so quiet. You only really hear like adult buzz every so often. So

Nic L  2:05  
until he drills the holes to run the wires.

John P  2:08  
I kind of want to see like, I want to see somebody drilling a hole like into one of your Lego sets and just see it like no teetering towards the edge like,

Nic L  2:16  
no, no, no, no,

John P  2:18  
no, no, no, no, we're not doing that. All right. So we have an update this week. And it comes from a listener, Nic want to tell us more about that.

Nic L  2:31  
Yeah, we had some listener feedback from me. Thank you, me for sending us that email. He mentioned after listening to our episode from last week talking about the book module, there is an issue on drupal.org right now sponsoring look to be removed from core. So if that's something that you use, apparently, there's a policy in Drupal, which I think makes sense that if modules are used by less than 5% of the installed base, they should be removed before the next major version. So if you think books should be an exception, you should comment on that issue, which will be in the show notes. Or you should install it on more sites so that more than 5% of users are using the book module.

John P  3:11  
It's interesting because I'm it actually, he sent us an email and a lot of the points that he made in it, where he found issues with the book module, like he said that he loves using the book module and so I use case for it. But he highlighted some things that he thought like around permissions that he thought could be better. And I'm wondering if when it goes to the contrib space, if it'll be easier for people to kind of fix those things because they won't necessarily have to make a changes to Drupal Core. So I will not install the module more. I will not comment on the issue. I will let it let it do what it's going to do.

Nic L  3:51  
I'm going to set up a cron job that sets up called module 1000 times a day until

John P  3:57  
If you want to send Nick messages about his his cron job, you can will find that his contact information at the end of the show.

Let's move on we actually have a drop in or a note from the New England Drupal camp which Nick and I helped to organize. So here's Stephen to tell you more. The New England Drupal camp is back in person at Rhode Island College in November. NEDCAMP as we call it is a two day Drupal camp Friday being a training day and Saturday sessions. Session submissions are now open. New presenters are encouraged and welcome. Did you know Nick and John a camp founders and are still on the organizing team join John and Nick and the other New England Drupalers in November. You can learn more visit Nedcamp.org

Thanks, Steven. We're looking forward to everybody coming to Providence in November. So as Steven said, You Find out more at netcamp.org. All right, let's jump into our primary topic. I am super excited to talk about this because I know about Graph QL. And you can tell by the way, I said that, like, I know enough to like, say, hey, it's Graph QL. But, you know, I'm really looking forward to kind of jumping in and learning a bunch more about it today. So, Alexandra, let's start with the really basic softball question. What is graph QL?

Alexandra V  5:32  
Okay, so Graph QL is a query language. That's the QL in the name. I think there's been some debate on whether it's actually a graph or not. I don't have a math background. So that's a debate I'm not getting into. But it was originally designed by Facebook to make the data that they have accessible within their products. And they also use it internally. And I think, what is the real power of Graph QL is that it puts all the tools in the hands of the clients to specify what data it needs. So that's where the query language of it comes in, is that the clients can ask the server for? Yeah, the data that they that they want.

John P  6:21  
So can it be used? Like you saying query, right, yeah. And when I think query, I think like a MySQL database, let's query this thing. Can it be used to query a database like MySQL? Or is it just for like ingesting API's?

Alexandra V  6:38  
Not directly. So the Graph QL language would always be used by address field client to query a Graph QL server. And then the way that these both behave is actually defined by the Graph QL specification. So this was originally started by Facebook, but it's now owned and maintained by the Graph QL foundation. So there is a specification document that actually very clearly outlines how this works, and how the type system of Graph QL works. I think that's if we start getting into differences, maybe with something with something like JSON API. Then Graph QL has its own internal type system that you use to define what a Graph QL API would look like, and how a client would talk to it.

Nic L  7:27  
Yeah, my understanding is one of the powers of Graph QL was it's generally meant to be against NoSQL databases. So you can build those relationships kind of on the fly. And, and you can point it against something like MySQL or Postgres, but you have to have some sort of mapping layer. In between.

Alexandra V  7:45  
Yeah, exactly. So in Graph QL, we often talk about resolvers, which is what runs on the server. And the result for it takes a part of a graph, QL request, usually a field, and then it goes and fetches data for it. And what that data actually, that data source actually is, could be anything, it could be a database, it could be a flat file, it could be another Graph QL API, as well. So while with graph, QL, you don't query the data source directly, you would query a server that knows how to actually fetch the data using those results.

Ryan P  8:21  
Yeah, when I think about Graph QL, I think, for me, the killer app of it is that when I ask for information, I'm allowed to describe the way that I want to get it back. Right. So I can say, Please give me an object called solar system, and I want to have in their planet, and I want to have the mass of the planet and the distance from the sun. But all that other stuff that you know about planets, please just don't tell me. But I do want you to tell me the names of the moons and what all of their other possible nicknames are. And you can like dive really, really, really deep and get a bunch of information about the moons without having to do like a joint statement, you can just say, give me all this information, get it in one giant object, graph tree thing. And then when I get it back, I've essentially done sort of like one query for my whole page, whatever it is that I'm trying to render, and then I move on, and I may never have to go back to the server again.

Alexandra V  9:23  
Yeah, exactly. Yeah, it's really designed to be able to say, to express all of your data needs in a single query, rather than have the client go back and forth to the server to keep fetching additional data as it learns more about the data.

Nic L  9:41  
So So what are the what are the main use cases for Graph QL? Then?

Alexandra V  9:46  
So I guess I can give some examples of organizations using Graph QL. So of course, there's Facebook who use it internally. Funnily enough, they don't expose it publicly. They do have a graph API. But that is not a Graph QL API, it's just named the graph API. Shopify does have Republic Graph QL API and uses it for all its admin and shop related data. So that's really meant to build applications that use data from Shopify, like storefronts. Similarly, GitHub exposes all of their repository data and data about organizations and users using Graph QL. And they actually say in their documentation that the Graph QL API they offer offers more precise and flexible query than the GitHub REST API. So they're also really trying to push their API users towards Graph QL. Because they can, more specifically, yeah, fetch data. If you look, if you look at Graph QL, itself, it's based around three operations, the first operation is query. So that's really for fetching data, then you also have a mutation operation, which is to make a change. And while the name is mutation, you could also provide mutation fields in Graph QL with the name of an action. So I have seen at Graph QL galaxy, which is a conference around Graph QL, that people have built remote procedure calls on the Graph QL specification. I don't think it was something they wouldn't necessarily recommend. But it's definitely possible. And the final Graph QL operation is actually subscriptions, which you can use to set up a real time connection and to get data from the server as it's created on the server or as new events happen. So you can receive live updates on the client.

Ryan P  11:52  
So that's, that's actually interesting that you can do real time. It kind of makes me wonder, you know, when you think about other ways that we could get output from an API or other ways that we could describe an API, you know, pretty native to Drupal at this point is the JSON API spec. It definitely has its own sort of, like set of achievements that you can get to and challenges, but what are some of the main differences between something like Graph QL and JSON API?

Alexandra V  12:21  
Yeah, so this is actually something we've had quite a debate about at OpenSocial. Before we decided to adopt Graph QL. And I think the outcome is that you can achieve probably whatever you want with either methods. So whenever people are trying to choose, I always say slightly unhelpful, that it doesn't matter too much. But for us, it really came down to where do you want to put the bulk of their efforts? I think JSON API works really well for Drupal. Because from a server perspective, it's really easy to adopt. Since I can just map my data to the API, and then let the clients figure out how they want to assemble that data. That means you put a lot of the burden with the client. And you're going to need tools, right, like React query to help you fetch that efficiently and make sure that you use includes properly to actually fetch whole objects and make sure you don't have to make 10 requests to the API. And I think, Graph QL can really shine in that area of unburdening the client. And that's also why we chose that OpenSocial, because you will need to do quite a bit more work on the server, I think, especially with with Drupal. But that does mean that you do that effort on the server and that your client can be a lot simpler, because it can just say, this is the data I want in the spirit that I want it and this is the data I get. And I think that's very powerful, a lot more back end developers than we do front end developers. So it makes sense to actually push that to the backends.

Ryan P  14:04  
Yeah, one thing I think about, you know, I think I mentioned this already about doing like a database join is, you know, something like JSON API, if the data is not available in the one call that you made. Now, you're sort of having to go make a couple of round trips. But at the same time, the stress of having to implement that right for the backend developers is pretty minimal. So there's definitely some trade offs like Graph QL. I've definitely heard people talk about I haven't done much with it myself as on the back end, but having to make the middleware sort of robust enough to support all the different things that people might ever want to do with it. can take some time, right?

Alexandra V  14:47  
Yeah, exactly.

Nic L  14:49  
And sometimes it can also you have to be careful because it can be more. It can be a lot slower in some cases, too. So for example, I'm working on a project right now that uses Graph QL extensively its not even a Drupal project, but they're using Postgres in the back end. And then they use Graph QL to allow like a really robust API, as you said, but when you have really complex queries that cross multiple services, especially if you're in a microservice architecture, then those can become very, very slow. Because each time you cross that boundary, you need to, like Graph QL, on the back end has to has to make those round trips. So those requests can take a lot of time. So there are still cases where even if you're using Graph QL, primarily, sometimes you you write some queries in the backend, and then expose those to Graph QL. So people can get those responses. But but but you're doing all the joins properly in a, you know, with a direct sequel file or something just so that it's more efficient.

Alexandra V  15:52  
I would I would challenge the conclusion, that means that Graph QL is slow. Especially if you're saying like we talked to different. Yeah, it's just like, that's, that's true. But if you would do that in another API shape, you would probably still have those boundary crossings. And

Nic L  16:09  
yeah, it's a limitation of the product architecture, not a limitation of Graph QL. And that's true, like you said, of any other API to like, so there's still it's not. The point is, it's not a cure all. It's not like you put Graph QL and put it in and then you can join infinite levels of data, and have it still be performant. You still have to kind of pay attention to metrics.

John P  16:32  
isn't the idea there really, that it, like your request is more like is more pinpointed as to what you want to get back? Right. So like, as opposed to, I think Ryan said this earlier, as opposed to like, you know, doing a direct query in MySQL, and writing a bunch of joins or using JSON API and having to call like, three different API's and get all of their data back and then pulling like each little piece that you need from each one. You can say, hey, Graph QL, I need this, this and this. And it'll it'll basically return this, this and this, which makes the request a lot smaller and a lot more manageable. Right? That's, that's the goal there.

Alexandra V  17:15  
Yeah, yeah, the Graph QL API would still need to go fetch that. So if the client makes up a query that that's crosses three services that you would need to do those individual requests. But I didn't think one of the one of the interesting things about having, knowing all the data the user wants is that you can start thinking about smart optimizations and parallelizing those. Yeah, on the server, but that is definitely an implementation constitute would have to Yeah, carry to actually get benefits.

John P  17:48  
So I mean, my Graph QL to me, seems kind of like a almost like a middleware layer where you can I'm assuming you can manipulate the results. Like if somebody puts a request in you can you can manipulate the results you send back before you give it give it to them, like as far as the format of the of that and all that, right?

Alexandra V  18:07  
Yeah, yeah. So that's where the resolvers come in. I think if you look at if we start looking, for example, at how this works, in Drupal, then resolvers in Drupal are very much using the API and the entity API to go fetch data. But that could mean that a single field and a response actually uses multiple entity types to generate the data. Sure. So that's, that's one of the powers at least for us at OpenSocial. That we that we thought it's we often have things that are slightly related, or that maybe use more than one piece of data to get to a value. And resolvers make that really easy, because our API shape is in no way tied to our data storage.

John P  18:54  
Interesting. So we talked earlier on about common use cases. I'm wondering, you know, how you've seen people using Graph QL today. And if there are any interesting use cases you've seen either at Open Social or, you know, outside and in the wider community.

Alexandra V  19:11  
So one of the interesting use cases that I've that I find interesting that I've built myself at OpenSocial is our real time chat. So this is actually the data storage, it's powered by Drupal. Drupal itself does not support persistent connections. So you Drupal cannot handle subscriptions. But what we essentially did is we built a separate PHP service that could handle the subscription aspect, and would just communicate with the Drupal installation to to serve. Yeah, so that's how we got got the real time chat working as a feature on top of a Drupal site. I did a lightning talk about that at Graph QL galaxy that details a little bit more on the architecture and and the technologies involved.

John P  19:58  
So so damn good. dumb guy question who like super high level? So both folks involved in the chat or all the folks involved in the chat, if it's a multi person chat, I would imagine, are using some sort of front end interface. Maybe it's react whatever connecting to Graph QL. And then Graph QL is basically going out to Drupal, which is the data store and pulling the relevant pieces and kind of stitching them together to make that chat experience.

Alexandra V  20:25  
Yeah, exactly. So basically, what we did is we have this subscription server, which handles the subscription operation of a Graph QL request. So every user would be running a Graph QL client within the within the user interface, that would set up a connection using WebSockets. And just send this subscription operation over the socket connection. And then sending a chat message is actually a mutation. So that's just a field that's literally that sent a message that would go directly to Drupal. And then we use the event system in Drupal to put an event on RabbitMQ, that is then seen by this description servers, which would then fetch the data actually, from the Drupal actual API, forward that into the subscription, WebSocket connection, to push the update to the clients that are connected.

Nic L  21:24  
Sounds easy (laugh)

Alexandra V  21:28  
It took a good nine months to figure out and get into production. But yeah, once like, in hindsight, it's it Yeah. In hindsight, it's doable. It was, it was a challenge, figuring out how to actually serve the subscriptions, well storing the data in Drupal.

John P  21:48  
I'm gonna go down one small rabbit, well, maybe not small, but we're gonna go down one rabbit hole here. I'm just curious why this solution for a chat client as opposed to a third party service, or an existing as an existing solution.

Alexandra V  22:04  
So OpenSocial builds community software that we sell to our customers and as Software as a Service fashion. And each of our customers have their own installation. Because we like one of our primary selling points, and something that we find very important is privacy. There are chat services out there, that would probably have been easier to integrate, but they usually want payment per installation. So scaling this out across all of our customers would quickly. Yeah, good cause to the secondary consideration is that if we have an external chat server friends, that also means we need to get all of our customers to agree that that chat service is going to be handling and storing their data. Whereas right now, we can just say, look, all the chat messages being sent to your platform are gonna be stored in the same Drupal database that is already handling all of the other user data and other content that they might find important.

Nic L  23:08  
So So what are some of the big challenges when you start integrating Drupal with Graph QL?

Alexandra V  23:17  
I think the first one is understanding Graph QL. At Drupal module, if you look, if you look at Graph QL, in the wider PHP ecosystem, there is actually a Graph QL library that mimics the JavaScript implementation of the Graph QL specification. It does so in a way that actually mimics the file structure of the JavaScript implementation, which is sometimes a little weird if you're used to PHP. But as someone who didn't know, the Graph QL implementation and wanted to contribute a feature to that library, it actually meant I could mostly just translate what was happening already in the, in the JavaScript implementation, I didn't need to reinvent the wheel. What the Drupal module actually does is it takes that library, and it links it up with Drupal plug in system so that you can actually define your schema and actually define your resolvers. I did a deep dive about this at DrupalCon North America on really going into the weeds of how the module works internally, and I will be giving the same presentation at DrupalCon Europe if people are people are there. But you're at the moment, one of the difficulties that users face when they start out with looking at the module is that there's two versions. There's version three of the module. And what that did is actually do the same as the JSON API, which is it takes the data model of Drupal, and it tries to expose all of that as a Graph QL API. And that works. That's easy to get to up and running, but you lose some of those advantages of Graph QL are really being able to shape the API towards the use cases of your clients, rather than just dumping out your data model. So the maintainers of the Drupal module actually made a new version, version four. And that did things completely differently, it doesn't really give you anything out of the box accepts the examples that are included in the in the module. And it requires you to write your own schema using the Graph QL schema definition language, and then actually describe in a schema plugin, how that schema maps to resolvers, which are usually Drupal plugins that actually know how to fetch the data and provide a value. There has been some community work being done to create the Graph QL compose, I believe it's called, module that brings back some of that version three functionality to automatically expose your data in the Graph QL schema, but that's now opt in rather than the default.

Nic L  26:10  
So it sounds like it's actively supported. But many times it requires some technical expertise to really implement fully.

Alexandra V  26:19  
Yeah, yeah. Unless you're unless you're satisfied with just Yeah, exposing your data model as a as a Graph QL API, which can still work works fairly well, if you're saying, Hey, I just have a Drupal website, and I want to make a decoupled front end, and I maintain both of these. But if you're thinking about building an API that may also be used by other clients, other consumers, that you may not necessarily handle yourself, then you would probably have to invest some time and actually crafting a graph or designing a Graph QL schema?

Ryan P  27:02  
Yeah, that's something I hear pretty commonly as Graph QL. For an internal team, implementing it for yourself is way different than implementing it for the wide public. So we mentioned the chat application, are there other other notable uses of Graph QL? Inside OpenSocial?

Alexandra V  27:23  
Yeah, so one of the things we're currently working on outside of the chat is really to get our API up and running. One of the things that a colleague of mine has worked on is integrating authentication with Graph QL. So we can not specify in our schema, what kind of access rules, a user would need to actually be able to access the data. And that is for us also really, with an eye on being able to build an API that can be used by external developers to create applications against the social platforms that we host. And that's actually one of the interesting things we're running into, is that a lot of sites either create a private API, or a public API, and we're actually building one that will serve both because we also want to build a new React front end to Yeah, that uses the API to create the decoupled front end, rather than the Drupal front end we're currently using and eventually also move our mobile app over to using the Graph QL API.

Ryan P  28:29  
I don't know off the top of my head for Graph QL. But I know like for open API or Swagger definition, there's not really a great way to say what things you're allowed to do. Unless you're using Open API. There's sort of like a loophole there. Or sorry, not open API. We just said what it was called JSON API. No. Oauth. The other word that starts with O. O. OAuth, has this sort of spec that says what sort of grants you have, I think they call it but other means of authentication. I know in JSON API, don't have a way of describing your sort of permissions. So I don't know it just does Graph QL. No, have a way of describing what you're allowed to do. Or as you sort of like if you have this, everything that's in our API is open to you.

Alexandra V  29:23  
So Graph QL has something that is known as directives. And this is defined in this specification. And directives are either client or server defined extensions to Graph QL, if you will, that directs a client or server to adopt a certain kind of behavior. So what we've done for the oauth integration with Graph QL is on the server side, we've defined these directions and they look a little bit like like annotations as you would see in PHP doc. So they start with the @ symbol and then have a name and optional some arguments. And we've said we can either add those to a fields or to a type. And in those directives will specify what scope a client needs to actually be able to access that data or to access that. Yeah, that type of fields. And then the server can look into the schema. See those directions directives, and match that to an incoming Graph QL request that has some OAuth scopes attached to it.

Ryan P  30:29  
But yeah, that's, that's already pretty super advanced. If you're talking about like, you know, certain methods or certain fields that are only accessible, you've probably already gone way down the rabbit hole, into into API implementation lands. So for someone who's just, you know, wanting to try this out, don't don't worry about, you probably just have all the permissions or none.

Alexandra V  30:49  
Yeah, so it by default, the Graph QL module does integrate with the permission, just like the permission system. So the way that you could do this is if you have some data in your API that you know, needs some kind of Drupal permission, you could just make a request as a logged in user, and in your console for make sure that you're using the entity API correctly so that your query does the access check, or do an explicit permission check and just return empty data or an error. If the permission isn't there. So for us was really this advanced solution where we yeah, we want to have different types of clients. So both our internal clients, but also external clients that we may not know. And really be able to specify this throughout our API and document that as well.

Ryan P  31:44  
Does your company maintain any of those clients? Like is there like a, you know, open social mobile app or, you know, something that runs on a television or anything fun like that?

Alexandra V  31:56  
So the React from that that's what I'm working on? That's currently still in the, in the beginning phases. So while we have like, our chat has been built, it's running and production is being maintained. For a wider API, we're really still getting started. So actually, building this OS integration was one of the first important important steps for us.

John P  32:22  
And just trying to piggyback or clarify something that you just said. So the Graph QL Drupal module out of the box, will observe Drupal permissioning So like, if you are just getting started, and you're like hacking away, and you don't have access to a content type or something like that, that will carry through when you query Graph QL? Or through Graph QL?

Alexandra V  32:50  
Yeah, yeah.

John P  32:51  
Okay. Cool. That's, that's good to know. Because that's, that's always a that's always a concern for folks, I would imagine.

Alexandra V  32:59  
Yeah, yeah. So if you get if you get a little bit technical, then basically, we've contributed this one, which contributed additions to the simple auth module. And then the actual integration with Graph QL has been published as the Graph QL module, I would have to look it up. It's either Oh, scratch, Dr. Griffin. And what that basically does is it sets a different user when it senses that the request uses OAuth authentication. And then it basically delegates to the triple permission system, but it overrides a little bit one that would respond with depending on the scopes that are available in the request, state, you're not using a lot of thing you would still have to Drupal permission system. And you would either make your Graph QL request as an authenticated user, which is what we're actually doing for chat, because we didn't have our scopes yet. Or as an anonymous user, you would only be able to load anonymous data, given that you write your data producers correctly, because if you write a data producer where you disable access checks, then you won't have access checks anymore.

John P  34:09  
Right? And we shouldn't we shouldn't write those, we should always do the access checks. Yes, security first. So earlier on, you said that Facebook, kind of created Graph QL and Facebook's using Graph QL. And that might make some people feel achy. So I'm wondering how involved Facebook still is in Graph QL and who decides what's what's in Graph QL? And is there a standard around it similar to something like PHP or any of the other languages that are out there?

Alexandra V  34:50  
Yeah, so Graph QL itself is actually mostly a specifiction that you could find at spec.graphql.org by And similarly, the graph ql.org is the main introduction website, I would say two Graph QL. And both of these are actually owned and maintained by the Graph QL foundation. So they were transferred ownership of the of the Graph QL trademark and, and the spec. And there is within that foundation, there's a Graph QL working group of people who actually work on the specification. Yeah, and mostly guide the process of contributions that work on the specification, and Requests for Comments to propose new features actually happens in a GitHub repository. So anyone can see what is being discussed, anyone can log in and weigh in, I've actually done this in the past, just given my feedback of, hey, I'm seeing this, we're doing something with it. And this would be the impact. For us. This is why it's does sometimes take quite long. So I think one of the features that has been open for quite a long time is input unions. And an input type and Graph QL defines what what fields and types you can give to a mutation as user input. And then a union allows you to select of one of the different types, and an input type input union type would allow you to do that for mutation input. But there's been a lot of discussion about what would be the best implementation for that, and what are the trade offs with the existing language existing use cases, but also with future extendibility of the language. And I think there's now contributors from quite a few different companies actually part of the core graph, QL working group. But if you are running into something that you would like to see added to the language or the specification, then you could open up your own issue in the repository. But you'll have to commit to some time and work to actually jump in that. Yeah, work with feedback.

John P  37:12  
So so people don't have to feel icky about potentially using something that facebook has it's hands in

Ryan P  37:20  
reminds me of one of the very early days of React, discussion that I heard people having, you know, was like, Well, what happens if Facebook decides to take their toys and go home, but I think they've kind of proven themselves in the last, whatever it was 10 years or more, to be pretty good open source citizens. And, you know, once once a project gets used by enough people like, react definitely in this camp, you know, it'll get forked before it, you know, goes away.

Alexandra V  37:50  
Yeah, I think if you look at the organization, Facebook, like Shopify, GitHub, Airbnb, there's, there's some big names there, who will also we're also invested in making sure that, yeah, Graph QL continues. And since most of the API's are public, and they also want to have developers come work with them that already noticed this, they're also invested in making sure that it continues in a public fashion. So that's not that's not necessarily a risk I see for Graph QL.

Nic L  38:20  
So my next question is, is this then? So you you mentioned that, you know, there's an organization that maintains kind of contributions to Graph QL. But Graph QL itself is mostly just a spec. So my question is, when you're customizing things, are you must be customizing that in your implementation? Or, or do you really need to work on like, you mentioned, the the input merging, is that really just like a feature request? Because there's no like spec an agreed way to do it? And you can kind of do it yourself if you want to, but you're not sure if it's going to be supported long term? Or where is there an actual project you can contribute to as well.

Alexandra V  39:02  
So the idea is really that you stick to the specification, because you want to make sure that the API that you build can work with all of these different clients like a polo like relay. Having said that, there's actually a lot possible within the type system of Graph QL itself. So quite a bit of the of the automation or features from Graph QL clients, I've actually just been built by saying, I expect this shape of data. One of the earliest things I think was, for example, pagination by the relay client, where they said, we expect this kind of this shape of data to be returned for results rather than a simple list. And that allows us to automate fetching a page of a page of data and then getting the next page. Another feature that I mentioned before with OAuth that Graph QL has built in is directives. And these are really, yeah made to be specified by the server, or by the client. I think the only two default directives that are part of the specification are the skip, and if specification. So one of the interesting constraints for Graph QL clients is that Graph QL queries have to be static. Or at least, you could create dynamic queries at runtime, but you'll run into, you'll probably run into some issues with your with your client or performance reasons. But by using variables, which are also parts of the graph, QL specification in your query, you can actually use these to derive directives to tell the server Hey, I only want to have this part of the response, if the value that I pass in is, is true or false. So if you know that your user maybe has disabled feature, then you can tell the server Hey, skip this, if the user has disabled this feature, and the client would have to pass along the actually true or false values. Other interesting directives that the community is working on is the stream and the differ directives. So streaming is for lists. And this allows the client to indicate Hey, I know that if I add the stream directive to a list, and the server supports it, that you can get me an initial result set. And then outside of the of the graph, QL response, you can maybe add more results for this list. Similarly, defer is for fragments of a Graph QL query, where you can tell the server Hey, it's okay to send me this response and just sent the fragment of the query later. So using these directives, you can really develop the API and add new features and functionalities while still being spec compliant. One of the things that is defined in the Graph QL specification is actually how to inspect or introspect a Graph QL API, so that way, any Graph QL client can ask the server, hey, what does your data shape? What does your API shape look like? And also, what kind of directives Do you support? So that's how a client may know whether the stream or defer directives are available?

Ryan P  42:38  
Yeah, that's, it's a pretty interesting part of, you know, like, what, what makes Graph QL Interesting. I think we talked about that at the very beginning, but being able to discover all the things that are possible, that sort of this was built from the ground up to make that possible, right. That's, that was the whole point was API's, you know, the documentation was very fragmented, and sometimes it wasn't documented at all, you just sort of had to, like, start making calls and see what came back, like Graph QL, sort of like meant, meant to be this very discoverable. You know, like, almost human readable, kind of a thing. And if you look at some of the clients, you know, do you do you use? Do you have a favorite client that you're using when you're doing API development? And like, how has that enabled you to discover new things about Graph QL? And

Alexandra V  43:32  
what's possible? So there's actually two that I've used. The first is URQL, which is made by formidable labs Web Development Agency. That's what's currently powering our real time chat. I think their caching system has been really interesting in how Yeah, there method for how you would update the cache, how you can write functions to do that, and respond to new data, and be really selective about what you update on the client side and cause maybe changes in your UI. The second one is actually relay, which is created by Facebook. So using more Facebook technology, to build community platforms. And that has actually been what we've chosen to use for our new new web front ends. And the reason for that is that I've partnered with someone who works in the rescript community who actually maintains the rescripts bindings for the relay client. And he's been doing some really cool work building a router that integrates very closely with Graph QL and rescript. So that's also where things like defer come in, where we can really match a query to the shape of our UI and decide on a very granular level, what data is important for us to have immediately? And where we could maybe show a spinner and wait a little bit longer For the data?

Ryan P  45:14  
Yeah. So if you if you had to onboard, you know, a new person to your team tomorrow, where would you send them? Like, what what's the first three things you would tell somebody who says, I have to start working with Graph QL? Or I want to, you know, like, incorporate a Graph QL API into some application that I'm using?

Alexandra V  45:33  
Yeah. So I think the first resource that I would point people to is actually graphql.org. It's, it's basically the community maintained site. That explains what is Graph QL gives you the basics. And it's a good jumping off point, to other platforms. All of the developers that join OpenSocial actually are given a copy of the Production Ready Graph QL book by Mark Andre Giroux. And that's is a book that I wish I had when I got started. Because I've been doing a lot of searching around the internet, trying to solve all these problems that I encountered while working on the chat finding different blog posts that were either maybe a bit older, or sometimes like really new. And really, yeah, trying to figure out all the solutions myself, then I found the book. And it basically takes you from knowing nothing about Graph QL to an introduction of what it is designing, actually thinking about security, thinking about things like rate limiting, taking it into production, and also taking it Yeah, beyond having it in production and evolving your API continually to something like JSON API Graph QL doesn't actually have versions. So this means that you need to think about how are you going to add fields, you'll probably have to deprecate fields at some point where you'll just have to say to users, hey, we're monitoring how often these fields get called. And by someday it will actually remove them. But I've heard stories from companies where they deprecated, a field just saw that users kept going up, because there was no alternative to the field. So they decided, well, okay, we'll have to keep supporting the field, because apparently, it's useful to our clients. So things like that are all covered and in the book, and we give a copy of that to everyone that joins us and start working on one graph QL. That's super,

John P  47:37  
super interesting. So can we can we go down the rabbit hole one one last time on the deprecation angle, right? So like, I build this API, and I'm using the API, and then I decided, well, you know, we're going to deprecate this this thing, right? What does that mean? What does that look like? Both? Obviously, from the user side, it's like, hey, this goes away, and you get some sort of error message. But like, from, from a developer standpoint, do you have to kind of code around the, the, you know, the deprecation as far as like, Hey, we're gonna deprecate this and here's the error message you're gonna get, or does Graph QL. Just kind of handle that out of the box?

Alexandra V  48:18  
Yes, there is a deprecation or deprecated directive that you could add to a field. And ideally, you would includes in that a message that says why it's deprecated, what what you would recommend other people to do and maybe what is the scheduled removal dates. I think Shopify has quite a clearly defined process for this, for example, where they also publish this information to developers, and they take quite a long time period to actually remove a field. So between deprecation and removal, there may be quite some time. I think one of the most important parts of designing a Graph QL API. And that's actually where we now spend most of our time is, yeah, is thinking about this ahead of time, and being specific in. In naming your fields, you may be really tempted to name a field image, because it's an image. But try to suggest instead to your clients what the image is going to be used for, for example, is it actually the avatar of the user? Or is it their hero image or maybe their favorite image on the platform. And by being a bit more specific ahead of time, in your naming of fields, you're giving more clarity in your API, and you're also avoiding having to rename fields in the future because the name you really want is already taken.

Nic L  49:52  
So you're saying we shouldn't just call them Image one, Image two, Image three.

Alexandra V  49:57  
I mean, if you always have three It just and that makes sense for a planned application, go ahead and do it. I had to use that API. So similar,

John P  50:08  
similar to Drupal. Once you name a field, it's not the easiest thing in the world to change it. So thanks. Thanks before you before you name, right. Yeah.

Nic L  50:19  
Yeah, I mean, names are a resource, you should treat them as a valuable resource. And that's true of many things. So, Alexandra, thank you for joining us. This has been a great discussion on Graph QL. It feels like we dove in deep, but it was also pretty introductory, which I think is helpful, both for the three of us on the show and for our listeners. So thank you for joining us. But before we close out the show, is there anything else you'd like to share with our listeners?

Alexandra V  50:49  
Yeah, actually, so So one of the things that caught me off guard when I was getting into Graph QL. And I think this may be the case for many people using Drupal is that I was always really used to thinking about, about things in HTTP requests, and also HTTP semantics. And I think one of the things I would like to say to people is that it's important to realize that Graph QL itself is not tied to a transport mechanism. So it only defines, like the data shapes of the request and the response, but I could write this on a piece of paper, fax it to you or email it to you, and you could send it back to me, and we would still be spec compliant. So it can also be done over a real time connection, like WebSockets. Like I say, for the real time chat. We only use it for subscriptions, but we could also send our queries and mutations over that same WebSocket connection. And one question that people may have then is how do I cache? There's actually a really good video about that by Marc Andre Giroux, who explains that. If you have, if you have a spectrum of API customizability, to cache stability, then you'll see that as API's become more and more customizable, they'll become less easy to cache with customizable by mean, that the client can request more customized requests. So that's, that's a video that I'll add to the show. Now, it's definitely worth checking out for anyone who may be wondering how do i cache graph? QL? And how do I deal with that?

John P  52:42  
So going back to, like, I don't know, maybe maybe 20 minutes ago, now, when we were talking about, you know, basically getting the information you need out of Graph QL? Right Graph QL, kind of doing that join for you and querying those, those data points for you. Is there a mechanism or an ability to cache at that point where Graph QL can look at a cached data set, as opposed to like having to actually go out and get the dataset? Do the do the stuff to it?

Alexandra V  53:14  
Yeah, so there the there's a few levels. The Drupal module actually handles this on us on a field level, where it'll look at the fields, like the inputs that you may give to a field, as well as any context like is there maybe differences in permissions, you can specify those in the resolvers that you write, and it can store the outputs for a field. And if it says, hey, the inputs in the context are the same, I can just Yeah, give back the results rather than recalculating it. Also do this on a request. Although usually at that scale, it's slightly less useful because things may differ too much between requests. One of the things that has been created as an extension to Graph QL is actually persisted, queries. So what I can do is I can tell the server ahead of time, this is a query that I'm going to need in my application, I'll post it to slash Graph QL slash queries. And the server will give me back an identifier. And rather than sending the entire request, I can just send back the ID. So that doesn't really do caching directly. But does allow me to transport a Graph QL query over get, and it reduces the amount of data that I need to send. And it's I would do this, for example, for an anonymous Graph QL API that I could again, at that point, use an HTTP cache to cache that Graph QL request, but it really depends on what your use case are and how requests will differ from from one request to another on how you would approach caching.

Ryan P  55:01  
All right. And I actually feel like, as a Drupal show, we may have walked right past an elephant, and not realized it. But uh, one of the killer apps I think for for Drupal, especially for the site building crew is Drupal views, right. So, you know, views, I can look at all the data in my Drupal site, I can describe what fields I want, I can, you know, decide what format they're going to show up in. But at the same time, right, views sort of, by its nature is also trying to put out the HTML around those things. And then we have something like Graph QL, where it just saying like, all you want to get as the data but you as like the end point application can describe what structure you want that data to be. And maybe sometimes you get to make choices about what format you want those things to be in. But is there any sort of like, current connection, like in the graph, QL module between Graph QL and views or those things? You're either going to use a view or you're going to use Graph QL?

Alexandra V  56:05  
Yeah, there's no connection right now. So as I mentioned, the Graph QL compose module. I think they may have actually launched their betta yesterday or the day before, at the time of recording. They do like that module offers integration, I think with media with paragraphs, and just with with notes. And I can see that they may have plans to Yeah, over customizability there. So maybe they'll end up at something similar to fuse, where you take your Drupal data schema, and then use that to describe your API. But I think maybe views views directly. would be less useful there.

Ryan P  56:54  
Yeah, I mean, I saw like, there's some things in there about like describing routes and menu items and many attributes. So there's, there's a lot of like, interesting, sort of like native Drupal things, especially if you're familiar with the Drupal eight and nine world. But some one of the things I heard I was like, blokes, I didn't see that in here, but maybe it is. I'm

Alexandra V  57:18  
not too familiar with that. Yeah, we mostly write our own code to match up data to the to the API.

John P  57:28  
That it's that time of the show where I think we've gotten to the seeds in the stems, as they say in in winemaking. Alexander, thank you so much for joining us. And thank you to Nick's dog for for making an appearance. We really appreciate you coming on and talking to us about Graph QL.

Nic L  57:50  
My pleasure. Do you have questions or feedback, you can reach out to talking to people on Twitter with the handle talking to people or by email at Show@talkingdrupal.com You can connect with our hosts and other listeners on the Drupal slack in the talking Drupal channel. If you're interested in show news, upcoming Drupal camps local meetups and Chad's book corner, you can sign up for our newsletter at talkingdrupal.com/newsletter.

John P  58:14  
You can promote your Drupal community event on talking Drupal. Learn more at talkingdrupal.com/tdpromo.

Nic L  58:22  
And thank you patrons for supporting talking Drupal, your support is greatly appreciated. You can learn more about becoming a patron at talking drupal.com and choose become a patron.

John P  58:33  
All right, Alexander, if folks wanted to get a hold of you to talk about Graph QL or OpenSocial, or all things web, how would they go about doing that?

Alexandra V  58:42  
Yeah, so I'm in the Drupal slack, on drupal.org. And on Twitter under the handle @KingDutch where you can go to my websites  www.alexandervarwijk.com. And yeah, I was active on Twitter, if you want to reach me or Yeah, ping me in the graph. QL chat on the Drupal slack.

John P  59:03  
Great. Ryan, what about you?

Ryan P  59:05  
Yeah, I go by Liberator without the last vowel on pretty much every platform drupal.org and slack, Twitter, Instagram, things like that. So look for me and say hello. And if you happen to be in the Pacific Northwest, come to the Portland Drupal meetup. We are always doing something fun.

John P  59:25  
And Ryan, I forgot to say at the top of the show, but I think we owe you a happy birthday. Did you have a birthday yesterday or

Ryan P  59:32  
today as we record that's right. It is your my 40th trip around son.

Nic L  59:38  
Well, Happy Birthday gratulations

John P  59:41  
and looking for 40 or 50 more for you.

Ryan P  59:46  
Thanks very much.

John P  59:48  
Nick, where can people find you online?

Nic L  59:50  
You can find me online pretty much everywhere @nicxvan

John P  59:55  
and I'm John Picozzi. You can find me on all the major social networks and Drupal data work @johnpicozzi and you can find out about EPAM at epam.com.

Nic L  1:00:07  
And if you've enjoyed listening, we've enjoyed talking. See you guys next week. Have a good one everyone