Introduction to GraphQL

Hello and welcome to our first lesson. In this lesson we will cover the basics of GraphQL, we will learn what it is and how to use it, and we'll also understand how it fits the cursor's subject. In the course introduction, we mentioned that we were going to use a Postgres database to store our comments. In our application we need to be able to do two things. The first one is adding new comments, we want to insert new entries to the database. The second thing is displaying them in the UI, we want to extract the comments from the database. But how exactly do we communicate with the database from a front-end application? That's where Hasura comes into play. It will generate GraphQL APIs from a database, and that way from the front-end will communicate with Hasura through GraphQL, and beneath Hasura will handle accessing the database. And since we're going to use GraphQL, let's first talk about it a bit. From the official GraphQL documentation, we know that the GraphQL is a query language for APIs, and also it's a runtime for fulfilling those queries with your existing data. It provides a complete and understandable description of the data in your API, it gives clients the power to ask for exactly what they need, and nothing more. It also makes it easier to evolve APIs over time, and enables powerful developer tools. When we're working on an application that requires resources stored in a database, we don't directly access the database from the front-end code. We have a server for it. The client sends requests to the server to fetch or modify data. The server handles these requests, accessing the database and possibly performing some additional business logic. Then it returns a result to a client, it can be for example a list of items that the client application wanted to fetch, or a message that the request was successful. If something goes wrong, the server will return an error message. A common way to handle client-server communication, and you already might be familiar with it, is using REST APIs. Let's quickly take a look at it. With REST APIs, clients sends a request to a particular endpoint to access a particular resource. It needs to be sent using an HTTP method, expected by the server. Get post, put, patch, or delete. The request body and response format are usually a great app on between the front-end and the backend team, and the latter is implementing and exposing APIs that the front-end application can use. In this example REST API, you have three endpoints that accept get HTTP method. The first one returns a list of users, the second one can return a single user if you provide an ID, and in case you need more details of a user, you can use user details endpoint. Also, if you want to create a new user, you can send a post request to a user endpoint. Now let's move to GraphQL. A GraphQL server exposes only one endpoint, and it accepts only post requests. The body of the request is expected to be a stringified JSON object that contains a query and variables property. Here's an example. Query is a request written in GraphQL language, and variables is an object of values that you can use in the request. It's optional, and you can use it to pass some dynamic data to your query. Let's take it bit by bit. GraphQL schema. The core part of a GraphQL server is a GraphQL schema. It describes the data and functionalities available to the client applications. For example, for a GraphQL server created on top of a database with a single table users, the schema could look like this. We can see a query type with field users, and we know that if we use query users, we will get an array of objects of type user. The type user is described below. It has an ID name and age. This schema also tells us what types we can expect for particular fields. As we know that the returned name will always be a string, and age will be an integer and so on. Our tooling can use this knowledge to generate types for the GraphQL API. For example, GraphQL code generator generates types for types based on your schema. GraphQL query. To get data from a GraphQL service, we use a query. We construct it by specifying the root type, for example user, and all the fields we want from the type. For example, the server exposes fields ID, name, and age. But maybe we don't need all of them. One of the core concepts of GraphQL is the take which you want to approach. What doesn't mean? It means we can ask for exactly what we need. Let's say we only want user IDs. In that case, we can only specify ID field of the user type and nothing more. And the GraphQL server will only return user IDs. It won't return name and age. Example queries can look like this. All of them are valid and all of them mean the same thing. This is a request that the client application would send. You can see a JSON post body of a query field and a stringified GraphQL query. We can also pass the variables. Let's say you want to fetch a particular user based on the user ID. In that case, we can pass an additional variables field with a specified ID property. We can also provide a name for the query which accepts a dynamic ID value which then will be used in the query itself. In the next lesson, after we set up Hasura, we will play a bit with trying out GraphQL queries. GraphQL mutation. When we need to modify data, we are using mutations. With GraphQL mutation, we can update one or more objects. Take a look at the following example. We are using create user mutation, exposed from a GraphQL server. We pass dynamic values for a new user's name and age. And we also return an ID of a newly created user. It means that the mutation can not only be used to modify underlying resources, but we can also get some results back. GraphQL subscription. Sometimes, you may need real-time data. For example, you are building a chat application and you need to display up-to- date content. With GraphQL, we can subscribe to a real-time data from a server by using subscriptions. They have the same format as queries, with the only difference being a subscription keyword instead of a query. The subscription API is exposed over web sockets. Hence, we need to hit a web socket URL from a client. It means that instead of sending requests to the server on HTTP or HTTPS, we need to use a web socket protocol. Many GraphQL clients have built-in support for handling subscriptions. Client integration. As we mentioned before, sending GraphQL requests is no more than sending post requests over HTTP to an endpoint. For this reason, on the client, we can use built-in browser APIs. However, the GraphQL ecosystem is quite interesting, and there are multiple clients. For example, Apollo client, relay, or URLQL. They provide cash support, subscriptions support, improve the developer experience by abstracting the integration layer, and more. In case of bigger applications, it generally may be a good idea to use a Graph QL client. Why GraphQL? GraphQL is a very convenient way to work with JSON data. It can be used with any language or framework. It's not tied to any specific database, and on top of that, it has an excellent ecosystem and a huge community. GraphQL is statically typed, so as a front-end developer, we always know what to expect from the backend. What's more, GraphQL is introspective. We don't have to ask a server team about an API and its details. We can ask a GraphQL server for information about the supported queries. We can do it by using the introspection system. We can gain a lot of flexibility by using GraphQL. Instead of waiting for a new endpoint whenever we need to fetch a different set of data, we can handle it independently by writing an adequate query based on our specification. We also don't have to send multiple endpoints to fetch the information. We can handle it in one GraphQL query. Congratulations! You just learned the basics of GraphQL. It's a lot of new knowledge, but don't worry. We'll play a bit with queries and petitions in the following lesson, so that you'll have a chance to try different functionalities and experiment a bit with GraphQL. See you soon!