Introduction to GraphQL

Ask for Exactly What You Need

Imagine going to a library to get information about a specific author. With a traditional system, you might have to check out an entire encyclopedia volume just to read one paragraph. You get way more than you need, and you have to sift through it yourself.

GraphQL is a different approach. It's a query language for APIs that lets you ask for the exact information you want, like asking the librarian for just the single page about your author. This prevents the common problems of receiving too much data (over-fetching) or not enough data (under-fetching), which would require you to make another trip.

GraphQL is a query language for APIs and a runtime for executing those queries.

Instead of having multiple endpoints for different resources (like /users or /posts), a GraphQL API typically has a single endpoint. You send a query to this endpoint that describes the data you want, and the server sends back a JSON object with exactly that data.

The Schema: A Data Blueprint

How does the server know what data is available? Through a schema. The GraphQL schema is a detailed blueprint of all the data you can request. It defines the different types of objects and the fields they contain. This schema acts as a contract between the client and the server, ensuring both sides know what to expect.

type Character {
  id: ID!
  name: String!
  friends: [Character]
  appearsIn: [Episode]!
}

This code defines a Character type. It has fields like id and name. The exclamation mark (!) means the field is non-nullable; it must always have a value. The brackets around Character and Episode indicate a list of those types. This strong typing system prevents guesswork and reduces errors.

Reading and Changing Data

GraphQL has distinct operations for reading and writing data. They are clear and explicit, so you always know the intent of a request.

Query

noun

A read-only operation used to fetch data. Queries describe the data you want to retrieve from the server.

When you want to fetch data, you use a query. The structure of your query looks just like the JSON you want to receive. For example, if you want to find a specific character and their friends' names, your query would look like this:

query GetCharacterFriends {
  character(id: "1000") {
    name
    friends {
      name
    }
  }
}

The server would respond with a JSON object that perfectly matches the query's shape.

{
  "data": {
    "character": {
      "name": "Luke Skywalker",
      "friends": [
        { "name": "Han Solo" },
        { "name": "Leia Organa" },
        { "name": "C-3PO" }
      ]
    }
  }
}

When you need to create, update, or delete data, you use a mutation.

Mutation

noun

An operation that modifies data on the server. This includes creating, updating, or deleting data.

Mutations are structured just like queries, but they always start with the mutation keyword. They also allow you to fetch data back from the server in the same request, such as the ID of a newly created item.

mutation CreateReview {
  createReview(episode: JEDI, review: { stars: 5, commentary: "This is great!" }) {
    stars
    commentary
  }
}

Real-Time Updates with Subscriptions

What if you need data that updates in real time, like live comments on a post or a notification? For this, GraphQL provides subscriptions.

A subscription is a long-lasting connection to the server. The client subscribes to a specific event, and whenever that event happens, the server pushes the new data to the client. It’s like subscribing to a newsletter; you don't have to keep checking the website for new articles because they're sent directly to your inbox.

subscription OnNewComment {
  newComment(postId: "123") {
    id
    content
    author
  }
}

With this subscription, a client would automatically receive the details of any new comment added to the post with ID "123". This is a powerful way to build dynamic, interactive applications without constantly polling the server for changes.

Ready to check your understanding?

Quiz Questions 1/5

What are the main data-fetching problems that GraphQL is designed to solve compared to traditional REST APIs?

Quiz Questions 2/5

Which GraphQL operation should you use to create, update, or delete data on the server?

Apollo GraphQL Essentials