A GraphQL Tutorial for Beginners
GraphQL is a query language for APIs. In this lesson, we go through an initial discussion on GraphQL and how GraphQL differs from traditional REST APIs.
Get the project source code below, and follow along with the lesson material.
Download Project Source CodeTo set up the project on your local machine, please follow the directions provided in the README.md file. If you run into any issues with running the project source code, then feel free to reach out to the author in the course's Discord channel.
What is GraphQL?
📝 This lesson's quiz can be found - here.
🗒️ Solutions for this lesson's quiz can be found - here.
📖 This lesson's lecture slides can be found - here.
What we've built so far with our Node app conforms to what a REST (which stands for REpresentation State Transfer) API is. In traditional REST APIs, the client can interact with the server by accessing various endpoints to GET, POST, PUT, or DELETE data while leveraging the HTTP protocol.
To get all the listings in our app, we had to make a request to the /listings endpoint. If we wanted our server to serve data for just one listing, we could implement a /listing/:id endpoint (where :id is the dynamic id value of a certain listing). If we had mock user data, we could implement a /users endpoint to return all users or a /user/:id endpoint to serve user data for a certain user.
Now, let’s consider an example scenario. What if a client app needs to display some user information plus all the listings for that user. This client doesn’t have to be ours, someone else could have developed a web or mobile app that interacts with our API. How could this scenario play out with REST?
With an example REST API, the client could make a request to a /user/:id endpoint to fetch the initial user data.
1. `/user/:id` - to fetch certain user data
Then the client could make a second request to something like a /user/:id/listings endpoint to return all the listings for that user.
This lesson preview is part of the The newline Guide to Building Your First GraphQL Server with Node and TypeScript course and can be unlocked immediately with a \newline Pro subscription or a single-time purchase. Already have access to this course? Log in here.
Get unlimited access to The newline Guide to Building Your First GraphQL Server with Node and TypeScript, plus 70+ \newline books, guides and courses with the \newline Pro subscription.
[00:00 - 00:29] What we've built so far with our Node app conforms to a little more to what a REST API is, REST standing for Representation State Transfer. In traditional REST APIs, the client interacts with a server by accessing various endpoints to get, post, put, or delete data while leveraging the HTTP protocol.
[00:30 - 00:47] In our app to get all the listings we had to make a request to the /listings endpoint. If we wanted our server to serve data for just one listing, we could implement a /listing/id endpoint, where ID is a dynamic value.
[00:48 - 00:59] If we had users in our mock data, we could also implement a user /id endpoint to serve certain user data, and so on. Now let's consider an example scenario.
[01:00 - 01:09] A client app needs to display some user information plus all the listings for that user. Now this client doesn't have to be ours.
[01:10 - 01:19] Someone else can develop a web or mobile application that interacts with our API. How would we play out this scenario with REST?
[01:20 - 01:37] With an example REST API, the client would need to make a request to /user/id to fetch the initial user data for that particular ID. Then the client would have to make a second request to something maybe like user id /listings.
[01:38 - 01:45] That returns all the listings for that user. So far this isn't too bad, it's just two requests.
[01:46 - 01:53] Where does GraphQL fall in here? GraphQL is a query language for making requests to APIs.
[01:54 - 02:13] With the GraphQL, the client tells a server exactly what it needs and the server responds back with the data. GraphQL is not tied to any specific fronted or back-end technology, meaning you can use GraphQL with React, View, Node, Ruby, Rails, etc.
[02:14 - 02:26] Here is an example query where we attempt to query the user of a certain ID. And when we query this user, we can tell our GraphQL API which fields we want to be returned.
[02:27 - 02:40] In this case, we're saying we want the id field, the name field, and then for the listings for this user, we also want the id and title of these listings. Now GraphQL is also a typed language.
[02:41 - 02:56] So before we declare how we want each of these fields to be resolved in our back-end API, we have to tell GraphQL the type of the data we expect. We want the id to be of type GraphQL id, the name to be of type GraphQL string.
[02:57 - 03:07] We want the listings field to be of type a list of listing types. And the exclamation mark here is basically telling our API that this is a required field.
[03:08 - 03:22] GraphQL allows for some significant benefits. GraphQL APIs are intuitive because the client specifies exactly what data it needs, thus making the code intuitive and easy to understand.
[03:23 - 03:33] GraphQL APIs are performance because no useless data needs to be transferred. And as a result, reduced latency will make our app feel faster.
[03:34 - 03:40] This is especially important for slower internet connections. And GraphQL APIs are typed.
[03:41 - 03:53] GraphQL uses a type system of its own to validate requests. This integrates beautifully with TypeScript to create a robust, statically typed application.
[03:54 - 04:03] GraphQL APIs are also self-documenting. They encourage the use of GraphQL IDEs or integrated development environments.
[04:04 - 04:18] And GraphQL APIs also consist of a single endpoint. So for all the data that might be returned from a database or a server, everything is to be served within a single endpoint in GraphQL.
[04:19 - 04:29] Listings, a certain listing, users, a certain user, etc. As we've mentioned, GraphQL isn't tied to any specific technology.
[04:30 - 04:43] This is because GraphQL is a specification, not a direct implementation. The community has created several different implementations based on the tools and technologies we might be using.
[04:44 - 04:58] For example, there's the Apollo Server library for Node Frameworks, GraphQL Java for Java applications, GraphQL Ruby for Ruby applications, and a lot more. And this is the same for client tools as well.
[04:59 - 05:13] There's Apollo clients for the React, View, and other JavaScript client code that can exist. There's GraphQL Python to work with Python, GraphQL.client for .NET applications, and a lot more as well.
[05:14 - 05:25] This all might still sound pretty vague and too good to be true. So in the next lesson, we're going to go through an example-driven approach to compare a real REST and GraphQL API.
[05:26 - 05:37] We'll be using the GitHub API that has been made publicly available. And only after going through the next lesson will we come back and discuss some of the more core concepts of GraphQL.