Future-Proof GraphQL Schema Design

Hello, everyone. Today we're going to talk about building great GraphQL server experiences with GraphQL Yoga version 3.

First of all, I'm Loren, and I'm an open source developer at The Guild. You can find me on Twitter and GitHub where I'm mostly posting about open source development.

Before we start with the actual talk, let's have a few words about the Guild. So we at The Guild, we are a group of developers that have been doing open source since almost forever, and we assemble together for client work. And what we're doing is basically, we're working with clients solving their problems. And from there on we look at those issues, see how we can abstract them and share them with the world. And usually that will result in open source software that we then publish and make available for everyone. So basically, we solve problems and feed them back into open source.

So here's a short summary of some of our most prominent projects that we're currently having, which is basically code generator, which is a tool for generating code and type definitions for any language for your existing GraphQL server. And we have GraphQL mash, which is basically a library for converting any data source into a GraphQL SDK or gateway. We have GraphQL inspector, which is a schema validation and breaking change detection tool for UCI or CD flow. We also have GraphQL Hive, which is basically a GraphQL schema registry and insight platforms for Teams. It's available as a self-hosted version, but also as a SaaS version. Then we also have GraphQL tools, which is an utility for all kinds of GraphQL schema and server tooling that you might need. And then also very popular is GraphQL scholars, which is a scholar and data types, validation types for GraphQL GS. That is basically only a small excerpt of all the stuff we have. You can find more of that on the guild.dev. But today we're going to talk about GraphQL Yoga version 3.

So before we start with that, let's quickly give you a short overview of what happened in the past. How Yoga evolved and how we got to it until today. So I'll try to keep it short, so, someday in the past, Yoga was created by Prisma and the reason for that was that at this point all the available GraphQL server solutions that were already there were far too complicated. So for new people that started coming into the GraphQL space, they had a hard start for actually getting started with GraphQL. So Prisma took the existing Apollo server, wrapped it in another layer and out of that Yoga was born. Then shortly after that, the community saw this GraphQL Yoga server and for obvious reasons, ease of use and batteries included, they started adopting it. Then a while later, Prisma moved away from GraphQL. They introduced their own SDL, ditched GraphQL and inevitably then GraphQL Yoga ended up being unmaintained for a long time, actually. And a lot of GitHub issues and other issues, discussions piled up. That's when the guilt came in.

So last year we reached out to the Prisma team and asked them what's their plan for Yoga and whether we should help them out. And in the end we adopted Yoga, we got the repository transferred over to us, and then we started working on it.

The first milestone that we had in mind was Yoga version 2, and basically the mission behind Yoga version 2 was to bring the Yoga library back into a state where it's maintained, where all the existing issues and feedback got addressed, critical dependencies were updated, and yeah, that happened. About half a year ago, back in June, we finally released Yoga version 2. And then, just a month ago, we released GraphQL Yoga version 3.

But what happened from GraphQL Yoga version 2 to GraphQL Yoga version 3? That's what I'm going to talk about now. So actually in June, when we just released GraphQL Yoga version 2, all of the Guild members were assembling back in San Francisco and were sitting together and we were brainstorming about the GraphQL Server Vision that everyone had. Everyone had some kind of vision, but every individual in the Guild had different needs. And coming from different backgrounds and working on different customer projects, there were different needs.

So after a lot of intense discussions, we came to the following key points that are valuable. So first of all, it should be easy to get started. Like GraphQL Yoga Version 1 was easy to get started and GraphQL Yoga Version 2 was also easy to get started, we wanted to keep that for GraphQL Yoga Version 3. Then the other thing that we wanted to do is to make GraphQL Yoga Version 3 as production ready by default as possible. So batteries included. The details about this I'm going to talk to you about later. So then also, we wanted GraphQL Yoga to fit into any existing stack. And that does not mean, oh, I want to use it with Express, or with Fastify, or I want to use SDL first, or code first. When we said fit into any existing stack, we actually meant any existing JavaScript out there, whether it's Deno, Bunn, Cloudflare Workers, we wanted to support them all. Then also, we wanted to hide unnecessary complexity, which is kind of related to easy to get started. Yeah. Also, we wanted to provide solution paths for common problems, like persistent operations, Apollo Federation, all those fancy words that are out there. We wanted to address them and give solutions for them. And then in the end, we also wanted to allow people or individuals to solve their own specific needs with yoga without having to ditch yoga, or move out of yoga, or having to fork yoga, which basically means we wanted to have a plugin system that is as powerful as possible.

So, how did we achieve all those points? Let's start with easy to get started. So spinning up a GraphQL server with yoga is as easy as pie. With this code on the right, you get a full GraphQL server that supports all the latest GraphQL features. This exists in Platform Primitives, in this example, we are using Node with the HTTP module. So you can also see that yoga is not abstracting the Node HTTP handling away. It's just a request listener that you get from the yoga library and you can plug it into any HTTP server that's either specific for Node or Cloudflare workers or BAN or DNO. And then also from that you get everything, including a GraphQL IDE.

So another improvement that we did from yoga version two is we finally upgraded to GraphQL 2, which is just awesome. We are mind blown by it. You get a new fresh look, you have better usability, like 10 times better usability. Also, GraphQL runs locally compared to like other open-source GraphQL servers where they started not shipping an IDE with the GraphQL server and instead lure you into kind of using their self-hosted or cloud version of a Playground. And also the best thing about GraphQL version two is that it was entirely built by the community. It's open source, and we intend to maintain to it and make it even more awesome.

Then another thing that should be easy to use is GraphQL subscriptions. In the past, WebSockets were necessary for doing this because there were no alternatives actually. There's a huge history and incident between GraphQL subscriptions being not maintained and then people getting mad about it. And we thought, let's try a fresh approach, and let's try to use servers and events, which is basically simple HTTP and does not require any custom WebSocket protocol overhead. So our goal was that you can write your GraphQL subscription and then do a simple curl request from within your terminal for getting a full subscription working. And we made it work. So on the right you can see a simple subscription setup and on the upper left, lower left you can just see a curl request using the accept text event stream header, which indicates that we are dealing with a Nestervas and event stream. And that's it. You will get the events as they occur and the same as it works on curl, you can consume that in your browser.

Another feature that is in this back discussion since forever and we thought should finally be available in a JavaScript server by default is deference stream. It's such a powerful feature. It basically allows you to split your single query operation into parts where you know that certain parts are available faster and certain data is only available later because it's slow, it needs to do a database look up or whatever. Just splitting those fields on demand and then streaming them to the clients improves by a lot and by that you can build much more responsive applications. So far the only way for using this in GraphQL.js land was to actually install an experimental GraphQL version, get it to run with your existing server. But we solved it in different ways. So now you can actually use it without having to juggle around with this. You can just use GraphQL as it already is, GraphQL.js as it already is and use Yoga for getting started without any additional configuration.

So another thing that should be easy to get started is testing. In a lot of JavaScript frameworks, testing is always an afterthought. There's no documented way of doing that stuff. We wanted to make sure with Yoga that you get the full experience and answers for anything. We thought that the best way for testing is actually to use the fetch API, because that's how most developers are used to calling APIs in the first place. We thought, okay, on the Yoga instance, we would just expose a fetch function that will exactly behave like if I would call the Yoga server for my browser. That way, you can actually make sure that the tests are as close to real-world usage as possible.

The next thing we want to solve is to make Yoga production ready by default. As I said before, just from this code you get a full functioning GraphQL server. But also, in addition to that, you get all kinds of production ready defaults in the background, which includes error masking, validation and parser caching, health checks and even cores. So let's dive into them a bit.

First of all, error masking. Everyone knows that masking errors or leaking errors to your users is a security threat. In this example, we're calling a loadUser function on our DB object. That's a remote call, right? It tries to read from a database or something like that. Let's imagine that you've fucked up configuring the credentials. Then the connection might fail, and instead of resolving the user, actually an exception will be raised. If this exception gets to the user, there would be a security issue. For example, in this code, I took it a bit to the top, where the error message would actually contain, first of all, the IP and the credentials for accessing the database. That would be a fatal. And what we do instead by Yoga for any unexpected error or exception that occurs, we will mask that by default.

Then another bottleneck in many GraphQL servers is validation and parsing. In order to understand this, we first need to make sure that you understand what happens when you send a GraphQL request to the server. So first of all, we have a client and it makes a HTTP request to the server. Then the server is actually first responsible for parsing the request body and all the parameters, finding the correct route handler and then once the server identified that we're dealing with a GraphQL request, then actually the GraphQL execution engine kicks in. And it is basically made out of three parts. We have parsing, validation and execution and usually the bottlenecks are parsing and validating. Why? Let's show you.

So here we have an example of what parsing does. So before, so what the client sends to the server is a query operation document. Before we can process that query operation document we need to kind of convert it into an AST, an abstract syntax tree, which is basically an intermediate format that the execution layer will later on use for resolving data sources and the fields that are selected within the GraphQL operation. And the problem with parsing is that it's slow because it's CPU bound. So the parser would basically go through the send GraphQL operation and for each of those tokens it will calculate stuff. And in the end you get the AST out of it. If we execute the same operation over and over again, we don't need to parse it over and over again. What we can just do is slap an lru cache on top of the parser function and then when the same string is executed twice the cached AST can just be provided. Same is for the validation layer.

So in the validation layer with the AST that just got parsed from the parser layer will be validated with a set of rules. For example whether a specific field already is existent in our GraphQL schema. In this example we have a MeQuery with an id and a name that will pass because all those fields are available in the GraphQL schema and in the second example we also have a password field that is requested by the client but it does not exist in the server so instead get an error that contains or cannot query field password on type user. So validation is actually also expensive because it again needs iteration through the whole query operation and all its fields and because the results also are the same for every for the same query operation, we can also just slap an lxEU cache between that and the performance issue is solved.

GraphQL Yoga also comes with health checks by default. For example, our customers and us use Docker and Kubernetes heavily and there you need readiness checks, liveliness checks and stuff like that. It's built into Yoga by default because we think every GraphQL server or HTTP server should have built-in defaults for these by now. That's the industry standard. Then also Yoga deals with cross. I don't want to go into details there because who really understands cross? It just works okay.

The next big thing we want to address is that Yoga fits into any existing stack. As I said before, we're not talking about Node.js and all the frameworks that are built around it. I also want to talk about those new JavaScript runtimes, Cloudflare Workers, Deno, and BAM. For each of those, we wanted to provide an easy way of using it and also extending it. So if you're looking at our Xpress example, it's only slightly different from the one for using the Node HDB module. Instead of just passing it to the create server function, we create our Xpress app and then we just use Yoga as the middleware for Xpress. Easy as pie. If we're looking at BUN, we can just also create our Yoga request handler, pass it to BUN and that's it. Same for Dino. We create our request handler, pass it to the Dino specific serve function, that's it. And also for CloudFormWorkers, we create our Yoga request listener, attach it to the fetch event, that's it. So how does that even work? Because all those platforms are actually quite different from each other. Well, the solution here is the request and response model, that made popular by the Fetch API. And basically the idea is that request listener gets a request object and returns a response object. This was first made very popular by Cloudflare workers who adopted it. And they took it initially from the Fetch API. So within the browser, we have request and response for a long time, but now we also have it in the JavaScript server runtimes. And all those new wave JavaScript runtimes, Deno, BARN and Cloudflare workers already adopted this way of doing GraphQL, not GraphQL, HTTP request handlers. The only JavaScript runtime that's a bit late on that regard is Node. So in order to still support this with Node.js, we just built a small very light polyfill or adapter for Node.js that addresses this gap until Node.js catches up.

And this small layer is actually part of the Yoga Core. I want to thank here Ada, who made this all possible and came up with the initial idea. So, with this, by building the GraphQL engine and the HTTP server around those parameters, we got something that actually runs everywhere.

So, another part of fitting into an existing stack that was really important to us is that schema building should be possible in any way. Yoga should not be opinionated about how you build your schema. In fact, we actually ship a utility for doing an STL-first schema, but it's not mandatory. And if you don't want to use it, it won't be within your code. If you, for example, deploy Yoga to Cloudflare Workers, you will bundle your code. And we made sure that Yoga supports free shaking. If you don't use the utilities, they won't be part of the bundle. You can choose your own preference, whether you're using STL-first, using the GraphQL tools or GraphQL modules, if you're more in the enterprise sector, or whether you want to do code first with GraphQL.js, not recommended, POTUS or GQTX. It's your choice. Your schema, Yoga accepts any GraphQL schema.

Then, the next step for us that we wanted to make sure, is that Yoga is fully extendable. With Yoga version 2, we already made sure that parsing, validation, execution and subscribing is completely extendable, thanks to the envelope engine. But for Yoga version 3, we wanted to get a step further. Instead of only allowing to extend the GraphQL-specific things, we also wanted to allow taking full control of the HTTP flow. That means, hooking into routing, hooking into request parsing, hooking into response building, in addition to the existing hooks for parsing validation and execution. And from that, we were able to build very powerful plug-ins that some of them I'm going to showcase now one that we're very proud of is the response cache. Basically, it's a cache for GraphQL operations, so if you execute a query operation with the same variables over and over again, you can cache it either globally or by user session. And then when the GraphQL operation is executed in a second or a third or whatever time, the results will be served from the cache instead of the execution that you're having to re-execute the whole GraphQL operation. That can drastically reduce your server load and you can either store the GraphQL execution results in memory. Or if you have multiple server replicas, then you can use either Redis or Upstash as an alternative cache for shared cache between multiple instances.

Another thing is Automatic Persistent Queries. That was first made popular by Apollo, and basically it's a protocol for registering reoccurring GraphQL operations on a server in order to reduce client to server traffic. So a client can send an operation, register it, and then if it needs to re-execute the GraphQL operation, it can only send a hash on the second try, and the server already knows the operation from that hash, and thus the traffic from client to server is very low, because what we saw is that usually as your GraphQL operations get really big, the biggest bottleneck in the whole client to server scenario is actually the client uploading the GraphQL document to the server, and as before, it's just plug in your plugin and that's it.

Another thing is persistent operation, which is a bit similar to automatic persistent queries, but also adds another security layer, because where APQ allow to ad hoc register queries and to save brand worth, persistent operations only allow executing specific operations ahead of time. So any other GraphQL operation, except those that are in the persistent operations store that tries to get executed, will be rejected. And this is a pattern that we usually use in GraphQL production deployments, because there we usually want to avoid any arbitrary queries from clients we don't know. Another thing that we found very interesting is, what if we take a GraphQL API or schema and convert it into a REST API? Today we have a lot of debates around, oh, GraphQL versus REST, what is the better one? We think both have their use cases.

Why not develop your schema as a GraphQL schema and then convert it to a REST API. With this plugin, you also get the full Swagger experience, where you can try out your endpoints and document them, similar to what GraphQL does for GraphQL. Another thing that we are really proud of and very happy for the collaboration is GraphQL Armor, which is a collection of security plugins that's maintained by our friends from Escape and they basically provide a lot of utilities or plugins for public GraphQL APIs.

So if you are building a private GraphQL API and you want to go to production, probably persistent operations is your best bet, because this allows executing arbitrary operations. But if your core product is the GraphQL API and you have many clients and you can't determine which kind of GraphQL operations will be executed ahead of time, having a set of security plugins that prevent excessive usage of the GraphQL API is mandatory, in our opinion. So some of the plugins that are really cool is the Token Limit, which basically limits the amount of fields and tokens that a GraphQL operation can contain. Then we have the Operation Cost Limit so you can give fields a weight within your GraphQL schema. And if there's a query being executed that exceeds that query cost limit, it is automatically rejected. Depth limiting, classic one, probably the most well known one in the GraphQL space, Once your GraphQL query exceeds a certain depth, it's just rejected and also disabling field suggestions if you want to avoid people to auto-guess your schema. Then also we support Apollo Federation. So GraphQL Yolga can be both a gateway and the subgraph. So you can enjoy all the benefits you get from the Apollo ecosystem and use them in the Yolga ecosystem. And if that's not enough, you can still write your own plugins, right? So Yolga has a full flexible API for hooking into anything HTTP and GraphQL related, and you can solve your very use case specific needs or problems with your own plugins. And if your plugin is like solving a generic use case, and you think that other people benefit from it, you can share it with the community. On the Envelope website, we have basically a plugin hub with over 40 plugins that are either maintained by the Guild or community members, all around error handling, metrics tracing, authentication, authorization, caching and security. If you built a cool plugin, then reach out to us and we might feature it on there, because it might help other people aside from you.

And the last thing that we wanted to make sure is that GraphQL Yoga is actually battle tested in production. So our battleship for testing stuff is GraphQL Hive, which is our schema registry that serves billions of requests each month. Before we actually released GraphQL Yoga version 3, we were running it in Hive for a long time already. Also, our good friends from Redwood.js and ParseRer are already experimenting with the GraphQL Yoga version 3 and we are collaborating with them and upgrading that stuff, building a migration path for their users. So, that's all I have to say today. My last suggestion for you is to try out GraphQL Yoga version 3. Thank you.

Hey there! Hi, good to have you here. Thank you for having me. So, first question, first let's look at the poll question. So, you asked people what upcoming GraphQL features are they most hyped about. Let's look at the answer. So, the most, it's interesting, actually, the most popular answer was the one-off directive. Right after that, the deference stream, and far behind are fragment arguments and reclaimed control reliability.

I know you have a lot of opinions on each of those. Maybe you can describe very quickly just, you know, what is each and why do you think they matter? Yeah, sure. So, the one-off directive is there for actually solving the problem of input unions. So basically, if I have a mutation today, I have an input type, there's nothing like in union. And that's why there is this proposal of the on-off directive. You can annotate your input type with add one-off. And then you have basically input unions. It's basically probably also my favorite one, just to tease a bit. Is that you like with GraphQL, we had this thing. First, we had different endpoints, like single endpoints for fetching data, people wanted to put it into a graph and fetch everything together. But then they realized, oh, no, things are slow, because we have to wait until all the data is loaded. So this is actually a smart concept for like, then annotating certain things in the data that we want to fetch, and then get that as early as it is available, basically stream it to the client.

And then there's also fragment arguments, which in my opinion is very interesting. If you're using something like Relay, or in general use fragments for composing your componentry, because then you can compose all your fragments, pass arguments to those fragments and build your one query document for your whole application view. And then client-controlled nullability is a bit exotic. I still haven't figured it out 100%, but I talked to various people about this, and they see the main benefit in it, not for normal clients that try to write GraphQL queries, but more for gateways. Because what client-controlled nullability allows is to break the normal rules that exist in GraphQL today. For example, if you have a gateway that batches different queries into a single query operation and an error would happen, the operation would escalate till the next nullable field, and that could remove other responses from the query result. And if you can overwrite this behavior for a certain path, you can work around this. So for me, it's more of a gateway feature and also why very few – nobody voted for it.

By the way, I just want to remind people that if you have questions, you can go on Discord on the Dromeda Q&A channel and ask. I guess the first question for me, even related to this poll, is if people want to use these features already today and get the benefits of them, what can they do? So in terms of one-off unions, we have a plugin for this for Joga. Initially, we built this plugin for Envelop but you can use all Envelop plugins with Joga. Then for deferred stream, we also have a Joga plugin. In the past, it was really hard to use that. We made it easy. And for client control nullability, there's no plugin there and, obviously, apparently, no demand for it. And the last feature, I already forgot about the last feature. What was it? Fragment arguments. Yeah.

Oh, there's actually a half-done implementation in the pull request on the GraphQL.js repository. But apparently, nobody wants to finish it, and we haven't picked that up yet. But in terms of where we're heading with GraphQL Code Generator, and if we want to support this natively, we might pick that up soon.

Cool. So we have one minute, so one last question maybe. So you talked about Yoga v3. So what is your personal favorite Yoga feature out there that you think people should be most excited about? In my opinion, it's Deferred Stream. It's mind-blowing, because it solves a real issue with GraphQL and people that are moving to GraphQL have. Yeah, so that's probably my favorite one. Cool.

Yeah, so thank you so much, Lauren. This was really, really exciting and great to have you here. And of course, I'm really excited for everything that's coming to Yoga, but I'm very, very biased here. And, yeah, thanks for the talk. Cecilia, over to you.