GraphQL on Client

This lesson will cover how clients use GraphQL for retrieving information and why GraphQL is better than Rest API.

We'll cover the following

On the client-side

To illustrate conventional GraphQL communication practices, let’s imagine how a web or mobile application requests data from a server over HTTP (HyperText Transfer Protocol). At a high level, this conversation looks something like this:

The application sends a GraphQL document to the server. The server consults a schema that describes the available data that is queried and modified and then responds with a JSON document. Because of the schema, the server is empowered to fulfill the clients’ requests on a case-by-case basis.

REST API vs GraphQL

Let’s see how this compares to REST by looking at a specific example. In the example, we retrieve information about a specific user record.

In a REST API, we make an HTTP request that looks something like this (assuming a user ID of 123):

GET /users/123

As a client of this REST API, you have minimal control over what is returned. Perhaps the server will give you the user’s ID and a name. Alternatively, it may return the entirety of the user’s profile and every other record associated with the user. The contract between the client and the server is fairly one-sided; the client gets what the server wants to give it.

REST API authors try to address this problem using several different techniques and conventions. For example:

  • Writing detailed, custom documentation about API responses so clients know what to expect.

  • Supporting query parameters, like include and fields, that act as flags to select information, adding some limited flexibility.

  • Including references (either IDs or URLs) to related data, rather than embedding it. This effectively splits the query across multiple requests.

  • Using different resources to model different levels of data inclusion, for example, /users/123 as a full set of data and /profiles/123 as a sparse set of data. They also duplicate or reuse large chunks of code.

  • Splitting the API completely, perhaps by platform, for example, exposing /desktop/users/123, /mobile/users/123, to support the needs of different types of clients.

The GraphQL approach to this problem is more standardized and is based on specifying specific data and cohesiveness. GraphQL is an expressive query language focused on meeting API client’s flexibility needs.

For instance, if a GraphQL client wants to retrieve user 123, name, and email address, they explicitly specify those fields. This is shown below:

Press + to interact
{
  user(id: 123) {
    name
    email 
  }
}

Here, we look at three fields here: user, name, and email. We pass an id argument here, too, specifying which user we’d like to use.

GraphQL document determines exactly what the server’s response will look like. There are no hidden default values forced upon the client. Instead, the response is tailored-based on the request. Here’s an example response based on our previous GraphQL document:

Press + to interact
{
 "data": {
    "user": {
      "name": "Joe Bob",
      "email": "joe.bob@example.com"
     }
  }
}

The GraphQL server has the schema and knows what a user is, how to retrieve one by ID, and what information it can contain. The server can respond to the client with the information about the user that the client specifically requests.