Getting Started with GraphQL
Part 1: Introduction
This is part 1 of Getting Started with GraphQL series. We will be building a Netflix clone with GraphQL. You can check out the demo app here. The source code is available here. You can also play around with demo app’s graphiql here.
Index
- Part 1: Introduction (you are here)
- Part 2: Back-end
- Part 3: Front-end
- Part 4: Basic Features
- Part 5: Deployment
What is GraphQL?
According to the documentation, GraphQL is a query language for your API. But what does really mean? GraphQL was developed to solve a particular problem with RESTful API. Traditionally, the server says, “Hey clients, here’s the API I provide.” And the client requests the server what they want. But maybe the server returns too much data. Or maybe the client needs more than one API call to get what they want.
Problem 1 (the server returns too much)
Let’s say we are dealing with book data. Consider the API call getBooks() that will give you title, description, release year, and author name. Say you are building home page where you want to show all the books along with their title and description (no release year or author name). Then the client will be waiting for the server to send those unnecessary data. So you would go to the server code, create a new API call that will return just title and description, assign that function to a new API endpoint, and finally call that function from the client.
Problem 2 (the server returns too less)
Let’s say the server also provides an API call getBookDetails(id), which returns the details of a book with given id (e.g. number of pages, reviews, etc). Now on the front-end, you want to get all the books in the database with their title and number of pages. With vanilla REST API, you would need to call getBooks() to get all the books and for each book you call getBookDetails(id). Notice you are making multiple API calls here, so it’s very expensive (i.e. takes a lot of time). Again, you would have to go the server code, and create a new API endpoint that provides what the front-end needs with one API call.
This is very cumbersome. GraphQL solves this problem. With GraphQL, the client can request exactly what they want — nothing more, nothing less (without going to the server and add a new API endpoint). Check out the link below for more details.
GraphQL Ecosystem
GraphQL itself is just a query language. There are many packages that implements GraphQL. For example, express-graphql helps us glue GraphQL with express application. Apollo helps us connect front-end code with GraphQL. Here’s the gist of what’s going on when you add GraphQL to your existing application.
Server-side
To handle GraphQL queries coming from the client, the server needs to check whether the request is GraphQL. If it is, then you would hand the request over to the GraphQL server.
Client-side
Apollo Client provides an easy interface for us to interact with GraphQL server. We just need to write some simple code and Apollo will take care of the rest for us.
How GraphQL Works
An interviewer asked me “How does GraphQL works?” at Career Fair the other day, but I could not answer this question very well. If you have GraphQL project on your resume, make sure you can answer the question.
The core of this question is asking how backend knows what to return. Suppose there are Movie and Genre tables. Movie has id , title , and genreIds . Genre has id , name , and movieIds . First, we create something called entry point for Movie table (we will talk more about in next part). Essentially we tell GraphQL how to get a movie given an id. Then we tell GraphQL what the types of return values are. id and title are simply just strings. But genreIds are foreign keys to Genre table. So we tell GraphQL how to resolve these string of ids to the actual genre object. There’s no magic here. We need to explicitly tell GraphQL what the types of return values are. If they are not primitive types, then we tell GraphQL how to resolve it to collection of primitive data.
