A Guide to GraphQL Schema and Data Types

Now that we first hand saw the advantages of using GraphQL in a real-world example, let's dive into some core concepts. After playing around with the GitHub's GraphQL API in the previous lesson, we know that the GraphQL query language allows us to select properties on object types. For example, querying something like this, a listing object type, that has a title and a price field would allow us to gain data like this, where title and price return some information. But how do we know that the listing object type has a title or price property? Does it have more properties we can select? This is where the GraphQL schema comes in. Every GraphQL API has a schema which completely describes all the possible data we can request. Another good way to look at it is that the schema is the blueprint of a GraphQL API. When a request comes in, it's validated against that schema and processed accordingly. How does fields in the schema get processed? That's due to the second piece of a GraphQL API, the resolvers. Resolvers are functions that turn a GraphQL operation or request into data. We'll first talk about a GraphQL schema before we dive into discussing the topics within GraphQL resolvers. The most basic components of a GraphQL schema are the object types, which represent some kind of object we can query and what properties that object has. In the previous example, we could have an object like so. This type definition says this is an object type called listing. This listing object has a property called ID, which is a GraphQL ID. It also has a property called title, which is a string address, which is also a string and price, which is an integer. The definitions at the end of these fields refer to the type that is to be returned from these fields. The title fields expected to return a string, the address fields expected to return a string and so on. The syntax we're looking at here is known as the GraphQL schema language. We're going to talk about this some more as we start to introduce it into our node application. A GraphQL schema allows us to develop relationships between different object types. For example, we can say the listing object type can have a tenant field in which tenant is to be an object type of its own, for example, a user object type. Similarly, the user object type can have a similar but inverse relationship of its own, where it can contain a listing field that is to be the listing object type. These are sort of one-to-one relationships where listing can return a particular user and the user can return a particular listing. We could also have one-to-many relationships where we can example say the user object type has a listings field that return a list of listings. In the GraphQL schema language, we can define a GraphQL list by using the square brackets syntax. Here, which states we're returning a list of the listing object type. There are two special object types within a GraphQL schema called the query and mutation object types. Every GraphQL schema must have a query type and may or may not have a mutation type. Query and mutation represent the entry points of every GraphQL query. The purpose of a query type is to define all the possible entry points for fetching data. The purpose of the mutation type is to define all the possible entry points for manipulating data. Here's an example of a query object type that allows us to query a field known as listings. Similarly, we can have a mutation object type that has a field labeled "Delete Listing" which takes ideas and arguments and according to its name would most likely delete a listing. The listings query and delete listing mutation both return variations of the listing type that we could have defined earlier. A GraphQL object type has one or more properties, but at some point, these properties must resolve to some concrete data. That's where these scalar types come in. They represent basic data types that do not have any more nested properties. GraphQL comes with a set of default scalar types out of the box. Boolean, true or false, int, assigned 32-bit integer, float, assigned double precision floating point number, in other words a decimal number, string, a UTF-8 character sequence, ID, which is similar to string, but it's used to represent a unique identifier in GraphQL , which is basically an identifier which is not intended to be human readable. Notice how some of these types are very similar to the basic types in Type Script? Inimoration types are a special kind of scalar type that are restricted to a defined set of allowed values. For example, let's say we wanted to add a listing type property for our listing object type, and we wanted to say the listing type can only be either a house or an apartment. This is where we can use an enumeration type to restrict the property to be one of these values. Objects, scalars, and enums are the only types we can define in GraphQL, but we can apply additional modifiers to affect our behavior. For example, let's say the listing object type is to have a bookings field. You've already seen this before, but in this particular case we're specifying the return to be a GraphQL list, which is denoted by the square brackets here in the Graph QL schema language. So we're stating that the bookings field is to return a list of values in which the values are to conform to the booking object type. Now one thing that we've glazed over that we haven't actually mentioned yet, notice that we haven't introduced any exclamation marks here. The exclamation mark refers to telling GraphQL that these fields have to conform to these types. In other words, these fields have to be required and can't be null values. In this case, we're saying that the bookings field could be a null value and the returned items within the array or list could also be a null value. When we look back at the other example we had before, by using the exclamation mark twice, we're saying we always expect a list with zero or more items, but in the particular list, we always expect every item to be defined as the listing type. Just like functions in any other programming language, we can pass arguments to fields. This is because fields are conceptually functions that return values. What if we needed to pass in multiple values to a create listing GraphQL field that will be able to resolve the intended results, which is have a listing be created. Just like we can pass in multiple arguments in a JavaScript function, we can pass in multiple arguments to a GraphQL field. In this case, we're saying this particular field expects the ID, title, address , and price arguments, and these are the respective types. Now, good convention will often find us creating input object types in situations like this, often valuable in the case of mutations, where we might want to pass in an entire object to be created. In the GraphQL schema language, input types look exactly the same as regular object types, but with the keyword input instead of type. In this case, we're saying the create listing field now takes a non-nullable input argument of type create listing inputs. We've come to understand that a GraphQL schema lays out the blueprint of how a GraphQL API is to be shaped. But how do these fields return values or make the changes we expect them to? We've mentioned this earlier, but this is where GraphQL resolvers come in. Resolvers are essentially functions or methods that resolve the value of a GraphQL field or GraphQL type. Every field in a GraphQL API is referenced with a resolver function responsible in returning the value of that field. With the original listings query we had in mind, a resolver can simply be a function that returns an array of listings that might have been defined elsewhere. The delete listing mutation resolver could have some additional functionality with regards to making the deletion before returning the expected value. And just like how these root level fields in the root mutation object types have the resolvers, the fields within the custom object types we can create have their own resolvers as well. For example, in this case we can say the ID is to resolve to an ID with an object titled to resolve to title within the object. These are known as trivial resolvers, so it's returning simply values within the past an object that is equal to the name of the field that we're actually declaring. So with that being said, you might be wondering what these objects or arguments or context arguments within the resolver function is. A GraphQL resolver would always receive four positional arguments. The first one is the object returned from the resolver on the parent field. For the root query and mutation object types, this argument is often not used in undefined. The second argument is the arguments provided to the field. The third argument is known as context, which is a value provided to every res olver and usually holds important context information, for example, the states of the currently logged in user. And finally, the fourth info argument is usually only used in advanced cases, but it contains information about the execution state of the query, such as the field name, the schema, the root value, etc. This introductory lesson only touches some of the main core concepts of GraphQL to give us a head start as we proceed. There are numerous other topics, both advanced and non-advanced like pagination , caching, union types, interfaces and so on. However, this will be more than enough to get us started and well on our way for the next couple of lessons. Keep in mind, we're going to reintroduce these topics as we begin to use them in the course. [BLANK_AUDIO]