GraphQL Introduction

GraphQL is a query language for APIs. Facebook created it in 2012 and released it publicly in 2015. It gives the client — your app or browser — the power to ask for exactly the data it needs, nothing more and nothing less.

The Restaurant Menu Analogy

Think of a traditional REST API like a fixed meal set in a restaurant. You order "Meal A" and the kitchen sends you soup, rice, salad, and dessert — even if you only wanted the rice.

GraphQL works like a custom order system. You tell the kitchen exactly what you want: "Give me rice and dessert only." The kitchen sends precisely that. No wasted data travels over the network.

  Your App                GraphQL Server
  ---------               ---------------
  "I need user name       [ Finds only
   and email only" ]  -->   name + email ]
                       <--  { name, email }

  Compare with REST:
  GET /user/1          -->  { id, name, email,
                              phone, address,
                              avatar, role,
                              createdAt, ... }
                       <--  (You wanted 2 fields,
                              you got 12)

Who Uses GraphQL

GitHub, Twitter, Shopify, Facebook, and thousands of companies use GraphQL in their production systems. It became popular because mobile apps need to save bandwidth, and GraphQL makes that easy.

One Endpoint, All Data

A REST API uses many URLs: /users, /posts, /comments. GraphQL uses a single endpoint — usually /graphql. Your query describes what you want, and the server handles the rest.

  REST API                    GraphQL API
  --------                    -----------
  GET /users/1                POST /graphql
  GET /users/1/posts          {
  GET /posts/5/comments         user(id: "1") {
  (3 round trips)                 name
                                  posts {
                                    title
                                    comments {
                                      text
                                    }
                                  }
                                }
                              }
                              (1 round trip)

Three Things GraphQL Can Do

Query — Read data from the server. This works like a GET request in REST.

Mutation — Write, update, or delete data. This works like POST, PUT, or DELETE.

Subscription — Listen for real-time updates. The server pushes new data to you automatically when something changes.

The Schema Is the Contract

GraphQL uses a schema to define all the data types and operations available. The schema acts as a contract between the client and the server. Both sides know exactly what data exists and what shape it takes. This removes guesswork and makes documentation automatic.

Key Points

• GraphQL is a query language for APIs, not a database technology.
• Clients request exactly the fields they need — no over-fetching or under-fetching.
• A single /graphql endpoint replaces many REST URLs.
• GraphQL supports queries (read), mutations (write), and subscriptions (real-time).
• The schema defines available data types and serves as automatic documentation.