REST vs GraphQL: APIs explained for beginners

What an API actually is, how REST and GraphQL each work with real examples, the practical differences, and which one a beginner should learn first.

An API lets one program request data or actions from another. REST organises an API around resources at fixed URLs, using standard HTTP methods such as GET and POST. GraphQL exposes a single endpoint where the client asks for exactly the fields it needs. Beginners should learn REST first, because it is more common and teaches how the web works.

APIs are how the front end of an app talks to its back end, how apps talk to payment gateways and maps, and how AI features call language models. Understanding them is non-negotiable for full-stack development. This guide explains both styles with small, readable examples.

What is an API?

Think of a restaurant. You do not walk into the kitchen; you give your order to a waiter, who brings back your food. An API is the waiter: a defined way to ask another system for something and get a response, without knowing how its kitchen works.

When a food delivery app shows your past orders, the app on your phone sends a request to the company’s server through an API, and the server sends back the data, usually as JSON, a simple text format for structured data.

How does REST work?

REST, a style described by Roy Fielding in his 2000 doctoral dissertation, organises an API around resources, such as users, orders or products, each with its own URL. You act on them using standard HTTP methods:

A request for one order and its response might look like this:

GET /orders/42

{
  "id": 42,
  "status": "delivered",
  "total": 499,
  "restaurant": { "id": 7, "name": "Kolkata Biryani House" },
  "items": [ { "name": "Chicken biryani", "qty": 1 } ]
}

The server also sends a status code: 200 for success, 201 when something was created, 404 when it was not found, 401 when you are not logged in, and 500 when the server itself failed. Learning to read these codes makes debugging far easier.

How does GraphQL work?

GraphQL takes a different approach. There is usually one endpoint, and the client sends a query describing exactly the data it wants, in the shape it wants it:

query {
  order(id: 42) {
    status
    restaurant { name }
  }
}

The response contains only those fields:

{
  "data": {
    "order": {
      "status": "delivered",
      "restaurant": { "name": "Kolkata Biryani House" }
    }
  }
}

Changes to data are made with mutations, which work like queries but create or update things. The server defines a schema, a typed description of everything that can be asked for, which also acts as documentation.

What are the practical differences?

How do you design a good REST API?

A few conventions make a REST API predictable and pleasant to use:

HTTP/1.1 404 Not Found

{
  "error": "order_not_found",
  "message": "No order with id 4242 exists."
}

Consistent errors save hours for whoever uses your API, including you six months later. Document every endpoint too, with an example request and response, so nobody has to read your code to use it.

What are over-fetching and under-fetching?

These are the two problems GraphQL was designed to address. Over-fetching means getting more data than you need: the order endpoint returns 30 fields when your screen shows two. Under-fetching means not getting enough in one go: you fetch an order, then the restaurant, then each item, in separate requests.

On a slow mobile connection, both matter. GraphQL lets a screen ask for exactly what it shows in one request. REST APIs can solve the same problems with well-designed endpoints and query parameters; it simply takes more deliberate design.

When should you choose each?

What should you know about API security?

Whichever style you use, the same basics apply. Require authentication for anything private, usually with tokens. Validate every input on the server, never trusting the client. Add rate limiting so one user cannot overwhelm the service. Configure CORS deliberately rather than allowing every origin. And never put secret API keys in front-end code, where anyone can read them in the browser. With GraphQL, also limit query depth and complexity, since a single deeply nested query can be very expensive to run.

Which should a beginner learn first?

REST. It builds directly on HTTP, which you need to understand anyway, and it is what you will meet most often: in payment gateways, maps, messaging services, and AI model APIs. Build a small REST API with a database, handle errors and status codes properly, secure it with authentication, and call it from a front end. Then learn GraphQL, which will make much more sense once you have felt the problems it solves.

Tools help: an API client for sending test requests, and your browser’s developer tools network tab for watching real requests. Both work from the command line too; our guide to Linux command line basics covers the terminal skills involved.

APIs sit in the middle of the skill stack described in Program Zero’s full-stack developer roadmap. In the programme itself, Phase 4 covers REST APIs with Node.js and Express, authentication, real-time features and GraphQL basics, with projects that build a full app on top of them. A deployed API with clear documentation is also a strong portfolio piece; our guide to building a developer portfolio explains how to present one.

Frequently asked questions

Related reading