Schema Type Definition

[00:00:00]
>> Scott Moss: Here, we're gonna talk about the schema definition language. So in the client side course, we talked more about the query language, which is, we'll also do a lot of that today for sure. But this server side course is specifically focused on the schema definition language. So what does it look like to make a graphical schema and everything that's involved?

[00:00:18]
So that's what we're gonna be doing today. if you've built any schema in your life whether it's a data base schema, some frontend validation, this is gonna feel very familiar, it's modeled after JSON and java script so if you've written java script it should feel pretty familiar. This isn't gonna feel foreign, honestly it feels like Typescript.

[00:00:37]
If you've ever written type script that's what GraphQL schemas feel like to me. They feel very much like TypeScript. And in fact, there's tons of tooling that will take a GraphQL schema and turn it to TypeScript and vice versa, because they're very similar in my opinion. So we're gonna talk about that.

[00:00:52]
At the same time, as I talk about it, I have a branch on the repo set up just for us to go and apply some of these things that I'm talking about as we do it. So let's walk through how we start that and get that set up, and then we'll walk through the schema definition linger.

[00:01:07]
So please follow along on this next part. So check out to the server/demo branch, it's a stripped down version of the repo. If you've worked on the client-side course, there were tons of files and react Stuff in there. This one's pretty bare bones, I'm just gonna walk you through it right quick.

[00:01:24]
So we have an app directory, this is a Next.js app, so there's a app directory here. But really only thing that we care about is this api folder inside, which has a graphql server, or I'm sorry, a graphql folder inside. And there's three files, there's a resolvers, a route and a schema.

[00:01:41]
What we're gonna do as we walk through some of the concepts of a graphql schema is we're gonna be working here in this schema file, and we're gonna just kinda play around with it. So, one of the things we can do is obviously start this. So, npm run dev is the command to start this.

[00:02:06]
>> Scott Moss: If you get an error trying to start, be sure to do a npm install. I went over at the beginning, that means you didn't have the modules installed, so make sure you do an empty install here. But start the server, it should put you on Mindsets Port 3 3,001 because I'm already on port 3,000.

[00:02:23]
So let me stop that and run it again. There we go, I'm on 3,000 now, so once you're there what you can do is, you can go to the browser, go to 3,000. You should just see a blank page that says home. That's fine, we're not doing react right now but you wanna go to /api/graphql.

[00:02:45]
And when you go here, you might get an error, right? And we're gonna talk about why you get an error. This is intentional, and this is showing you just how specific GraphQL is. So if you go to /api/graphql in your browser, you should get this error, unexpected EOF end of file.

[00:03:03]
I think that's what that means, so we're gonna fix this. We're gonna go through, and start talking about some of these types.
>> Scott Moss: Okay, so back to the notes. First thing, type definitions. What is the type definition? Basically, it's literally the building block of a GraphQL schema, or honestly, really any schema.

[00:03:26]
You can think of a type in a GraphQL schema as a table in a database, that's the best way I can describe it. It's not always gonna match one for one, you might have tables in your database that don't need GraphQL types. You might have GraphQL types that don't map to tables in a database.

[00:03:41]
Because you might not always be using a database with GraphQL. GraphQL doesn't care where your data comes from, so it's not always a one for one. But, if you're building a simple CRUD app, yeah, I would say your GraphQL types will align pretty heavily with your tables. Plus or minus some fields like passwords or combining, virtualizing one field into two fields, or the opposite of things like that.

[00:04:04]
So let's talk about what makes up a type. So we have something called a scholar type, a scholar type, or just primitive types in a programming language, GraphQL has a few of them. It has int for integer, so numbers, floats which are decimals. String, it's a string, it's exactly what it sounds like.

[00:04:24]
Boolean is true or false, and then ID. ID is literally the same thing, it can be a number or a string, but it just tells GraphQL this is a unique value. This is helpful for GraphQL tooling that does caching on a frontend and tries to resolve things by unique value.

[00:04:39]
So, but it basically just be any value that is considered unique. So those are scholar types, and then we have object types. So an object type is exactly what it sounds like, it's a more complicated type, so it's not just one field, but basically it is composed of other scholar types and other object types, right?

[00:05:02]
So here's an example of a user type that we're making. It has an id whose type is ID, this exclamation here means non null. So this is very common in a database where you can say, I have a field and it cannot be null. This is a required field, that's what the exclamation means required.

[00:05:20]
If you don't have exclamation next to it, it is not required. That's gonna make a big difference as we make a schema. So in the case of post, what you see here is, okay, I have a field called post. It is type array, so it's gonna be an array of another object type called post that's not shown here, but it does not have an exclamation mark, which means this field is not required, so it could be null.

[00:05:44]
So we're gonna dive into this a little bit. So let's go into our code, go into the schema, and we're going to make some things first. So the first thing we need to do is, and we're gonna make it first, and I'll talk about it in a minute, is we need to make what's called a query type.

[00:06:02]
What a capital Q, so if you say type Query like this and you kinda open it up like an object. And quick note, as you're writing this stuff, if you don't get syntax highlighting or things like that. There are tons of plugins. I'm using cursor, which is just a fork of VS Code so it's the same thing.

[00:06:23]
There are tons of plugins you can download that will give you the syntax highlighting for GraphQL. This comment that I'm using right here inside this template string is telling my editor that this is a GraphQL string and that's how I'm getting syntax highlighting you. You should also have that comment there, which will hint to your editor that this is graphic QL, and if you have the appropriate GraphQL plugin, it'll highlight for you.

[00:06:44]
But if it doesn't highlight, that doesn't mean it's not gonna change how it works. It's still gonna work the same, it just obviously doesn't look as good. It's like writing code in Google Docs, you don't wanna do that. It'll work, but probably don't wanna do it. So that's how I got the syntax highlighting.

[00:07:00]
And then what I'm gonna do here, we'll talk about the query type a little bit, but what I'm gonna do here is I'm going to make an object type. So let's do that, so I'm gonna say type person. It's an object type. And then let's give the person a name, which is a type string, okay?

[00:07:22]
>> Scott Moss: And then for us to get rid of this era that we're having and we can actually explore our schema. We need to write one query type. So what I'm gonna do here is I'm gonna make something called me. Make a query called me and it returns a person like this, and I'm just gonna hit Save.

[00:07:44]
>> Scott Moss: So I made an object type called person. It has a name field, which is type string. And I'm actually gonna make that required, so I'm gonna put an exclamation next to it.
>> Scott Moss: And on the query type, I made a field called me, and I said its type is called person.

[00:07:59]
I'm also gonna make that an exclamation, so that means the me field on query has to return a person. If it doesn't return a person, the server will blow up and the person type must have a field on it called name. That's a type string, if it doesn't, it will blow up, okay?

[00:08:19]
So that's a very simple GraphQL schema there, we go back to our browser, go back to our app. If we hit refresh, you'll now see this whole app load up.
>> Scott Moss: So why is it loading up now? Why was it not loading up before? We can talk about that.

[00:08:41]
>> Scott Moss: So if you go into the route.ts file in the GraphQL folder, this is actually where we're making the schema. Don't worry too much about what's going on here, you're gonna do this from scratch in a little bit, but this is kinda where I make the server, and the server cannot be created unless there is at least one query type.

[00:08:59]
You can think of a query type as like a Git request. Unless you have one Git request route to find in your GraphQL schema, it will not boot. It just won't work. So once we made that it worked, how do we actually get this app here? There's no code, if you go look, there's literally no code in here for this app.

[00:09:22]
So where does it coming from? That's actually part of the GraphQL schema, this is a tool called Apollo Studio. We're using an open source GraphQL server framework called Apollo. It's a company that makes GraphQL tools and they have built this app called Apollo Studio. You could think of it as like Postman or Insomnia, but for GraphQL, and it's built into your server.

[00:09:45]
You can turn it on, you can turn it off. We have it turned on and what it does is it runs an introspection query to your GraphQL query. It pulls down the entire schema, and then it builds an app around it, and it allows us to explore our schema.

[00:09:59]
So it's quite effective, it's very similar if you did like it. You can introspect SQL databases or MySQL databases or Postgres databases and see what the schema is, it's the same thing. This app introspects our server, pulls down the schema, and knows everything about it. In fact, I can go here to click on this button that says Schema and I can see the documentation for the schema that I just made.

[00:10:23]
So I can see I have a query type called me, returns a required person. I have an object type called person, and I have some scholars here. So if I click on the Object type person, you can see that it has a name field with a required string.

[00:10:40]
So I built all this for free, we don't have to do anything. And if I click on SDL here, I'll actually see the schema that we wrote.
>> Scott Moss: So that alone is just quite impressive. Imagine if you were building a developer facing product, which obviously needs tons of documentation, I don't think I've ever used a GraphQL API from a company where they built documentation from scratch.

[00:11:05]
I've never seen it, they'll just say, go here. Type in our URL into Apollo Studio, there's your documentation. You can see it all there, you can explore it, you can do whatever you want. There's no need for it, why would we write documentation when it can be generated?

[00:11:21]
So that's the great part, is like you just never see it. You don't need documentation for it, whereas with REST there's swagger. There's people making their own stuff, it gets it just gets complicated. But for GraphQL, it's pretty much standardized because this tool works with any GraphQL schema, period, so it just works.

[00:11:42]
Right, so let's go back to the Explorer and let's run our query. So I'm just gonna get rid of what I have here, let's use this query Explorer. So right now, you can see Root Type, we have Query, Query here. If you hit this + button, it'll just add it for you.

[00:11:57]
It's very cool, and I only have one field on the Query and it's called me. We made it, so I'm going to hit the + button on that. And then because me is an object type, it has to be expanded like this. You see these objects, these object brackets?

[00:12:11]
If I didn't put these object brackets, I couldn't run this query. If I just said, let me just do this. You can see it's already erroring, if I try to run this, it's gonna say no. Field me of type Person must have a selection of subfields. Did you mean me, {...}?

[00:12:27]
It knows that me returns the person type and the person type is an object type, so what fields do you want on me? Because it doesn't know, you have to be very specific of what you're asking for. Otherwise, you'll get this. We did not write the code for this input validation.

[00:12:42]
This was given to us for free because it's looking at the rules of the schema, right? And even our syntax highlighting, is aware of that. So we need to satisfy that constraint by making the object type, which still isn't enough. They just disable the button, no, that's not, [LAUGH].

[00:12:59]
You're not even gonna do it. So, there's only one field we can ask for and that's name. So I could just click here and it'll add name for me, I could have just typed it out as well. Then I run the Query and we get Hello World. So you might be asking, where the hell does Hello World come from?

[00:13:15]
We didn't write that, this is another cool feature of GraphQL because everything is typed. I can use this tool that will mock out all the data for my schema because it knows all the types of all the fields. So this tool takes our schema and mocks out all the return values without us having to write them.

[00:13:38]
Obviously, we don't want that in production. We're gonna use real data and talk to a database and that's what you're gonna do today, but just to prototype the schema and get things going, it's great. You can just mock this schema out right here, which is exactly what this code does.

[00:13:50]
It just looks at our GraphQL schema and mocks out every single field on it, given the type, because everything resolves to a scholar at some point. So it's just mocking out strings Integer, Floats, Booleans, and IDs. So those are just primitive types so it can mock those out pretty effectively.

[00:14:09]
And that's where Hello World comes from, that's this tool mocking it out. You can give this tool other functions to run to what mock data you want to return. But at that point, you might also just make real resolvers it might have been.
>> Scott Moss: Any questions so far?

[00:14:27]
If this is your first time experiencing GraphQL on the server, you might have your mind blown at this point just how free we were able to get some of this stuff. Cuz I know in REST, you would not be here right now. You might not ever get here, this is like a dream.

[00:14:41]
You worked at a company that had something like this built for their REST, API, you're probably at a great company cuz no one built stuff like this. They just default to swagger API swagger, API, and I hate the way the look, I hate how swagger looks. I just cannot stand the way that it look.

[00:14:57]
It blows my mind that it's like still looks like Bootstrap two or so. I don't, I can't stand it. But this right here just feels, you ever tried to use something like Swagger or any REST documentation and you wanna actually run the route and it's just so complicated.

[00:15:12]
You gotta click here, then you gotta sign in sometimes. And this is so complicated, I just want to just try this thing out right quick. And that's just so hard, but with this, you just try it out. You just run it right now, and we didn't have to write any code for it, so I think that's pretty impressive.