GraphQL Fundamentals
Introduction to GraphQL
A New Way to Talk to APIs
Imagine you're at a restaurant. With a traditional menu, you might order a fixed-price meal. You get the appetizer, the main course, and the dessert, whether you want them all or not. This is often how traditional APIs, like REST, work. You request information about a user, and you get everything—their name, address, shoe size, and their grandmother's birthday. This is called over-fetching, and it can waste bandwidth and slow down applications, especially on mobile devices.
Now, what if you just wanted the user's name and their last three posts? With REST, you might have to make one request for the user's info (and get all the extra data), and then another request to get their posts. This is under-fetching; the first request didn't give you enough information, forcing you to make another.
This is the exact problem Facebook faced in 2012 with its mobile app. To solve it, they created GraphQL. Open-sourced in 2015, GraphQL is a query language for APIs that lets you ask for exactly the data you need, all in a single request.
GraphQL allows clients to request exactly the data they need, reducing over-fetching and under-fetching of data.
How GraphQL Works
GraphQL organizes data into a graph, not a series of endpoints. Instead of having multiple URLs for different resources (like /users/1 or /posts/42), a GraphQL API typically has just one endpoint. You send a query to this single endpoint that describes the exact data structure you want back.
This is possible because of the schema. A GraphQL schema is a blueprint that defines every piece of data you can query. It lists all the available data types and the relationships between them. This schema acts as a contract between the client and the server, ensuring that the client knows exactly what data it can ask for and the server knows how to provide it.
Because the schema is strongly typed, it's also self-documenting. Developers can explore the schema to understand the API's capabilities without needing separate documentation. This makes building and using APIs faster and more intuitive.
GraphQL vs. REST
While both GraphQL and REST are used to build APIs, they approach data fetching very differently. REST is an architectural style that uses standard HTTP methods and multiple endpoints to represent resources. GraphQL is a query language with a single endpoint that gives the client control over the data it receives.
| Feature | REST | GraphQL |
|---|---|---|
| Data Fetching | Server-defined, fixed data structure per endpoint. | Client-defined, flexible data structure per query. |
| Endpoints | Multiple endpoints for different resources (e.g., /users, /posts). | Typically a single endpoint (e.g., /graphql). |
| Over/Under-fetching | Common issue, requiring multiple requests or receiving unwanted data. | Solved by allowing clients to specify exact data needs. |
| Documentation | Relies on external tools like Swagger/OpenAPI. | Self-documenting through its strongly-typed schema. |
For example, to get a user's name and the titles of their posts with REST, you might first hit GET /api/users/1 and then GET /api/users/1/posts. With GraphQL, you'd send a single query that looks something like this:
query {
user(id: "1") {
name
posts {
title
}
}
}
The server would then respond with a JSON object that perfectly matches the shape of your query. This efficiency is GraphQL's main advantage, especially for complex applications where data comes from multiple sources.
With GraphQL, you write one query asking for exactly what you want... one endpoint, one request, perfect data every time.
Time to check what you've learned.
What is the problem of "over-fetching" that GraphQL aims to solve?
According to the text, what is a key structural difference between a typical REST API and a GraphQL API?
GraphQL provides a powerful and flexible alternative to traditional REST APIs, giving front-end developers more control and improving efficiency. By understanding its core principles, you're ready to start exploring how to build and use these powerful APIs.