Chapter 4 — APIs, REST, and JSON

The why

An API is the contract that lets two programs work without either knowing how the other is built. Without it, every app would have to be rewritten every time anything changed.

What is an API, really?

API = Application Programming Interface. The official definition is "a set of definitions and protocols for building software." That's correct and useless.

The simple version: an API is a list of URLs your program can call, with rules about what each one does.

You've already used APIs:

• GET https://api.github.com/users/torvalds returns Linus Torvalds' GitHub profile as JSON.
• POST https://api.stripe.com/v1/charges creates a payment.
• GET https://api.openweathermap.org/data/2.5/weather?q=Mumbai returns Mumbai's weather.

Every backend you build is an API. You're publishing a list of URLs the frontend (or other backends) can call.

Why REST won

In the early 2000s the web tried lots of API styles — SOAP, XML-RPC, CORBA. They all lost to REST because REST was just the web already. REST is not a protocol. It's a philosophy. Five rules:

1. Everything is a resource. Users, posts, orders — each gets a URL.
2. Use the right HTTP method. GET to read, POST to create, PUT/PATCH to update, DELETE to remove.
3. Stateless. Each request carries everything the server needs (auth, params). No server-side session for the API itself.
4. Use status codes correctly. 200 means it worked, 404 means it doesn't exist.
5. JSON in, JSON out. (REST is technically format-agnostic but in practice it's JSON.)

That's it. That's REST.

GET    /api/users              # list all users
GET    /api/users/42           # one user
POST   /api/users              # create
PATCH  /api/users/42           # update
DELETE /api/users/42           # remove
GET    /api/users/42/posts     # all posts of user 42

Notice the nouns. No /getUser, no /createUser, no /deleteUserById. The HTTP method is the verb. The URL is the noun. This is the whole game.

Resource design — the part that's actually hard

Methods and status codes are easy. Naming resources is hard. Three rules to start:

1. Plural nouns. /users, not /user. Even for a single resource — you're navigating a collection.
2. Nest sparingly. /users/42/posts is fine. /users/42/posts/3/comments/8/replies/2/likes is misery.
3. Filters in query strings, not paths. /posts?author=42&status=published, not /posts/by-author/42/status/published.

What about non-resource actions? You'll occasionally want POST /payments/123/refund. That's fine — purists complain, real developers ship.

REST vs GraphQL vs gRPC

You will hear these three names a lot. Quick comparison:

For your first 5 years as a backend dev, REST is the right choice 80% of the time. Master it before you reach for the others.

JSON — the format you'll write 100,000 lines of

JSON = JavaScript Object Notation. Despite the name, every language can read it. Two shapes:

{
  "id": 42,
  "name": "Aditi",
  "tags": ["backend", "node"],
  "isAdmin": false,
  "joinedAt": "2024-08-12T11:23:45Z",
  "address

[1, 2, 3, "four", { "five": 5 }]

Rules:

• Strings use "double quotes". Single quotes break it.
• No trailing commas. {"a": 1,} is invalid JSON.
• Keys are strings: "id", not id.
• Six values: string, number, boolean, null, object, array. No undefined. No dates (use ISO 8601 strings). No comments.

Numbers — the silent footgun

JSON numbers are double-precision floats. They lose precision above 2⁵³. So if you're sending bigint IDs:

{"id": 9007199254740993}

This will be parsed by JS as 9007199254740992. Subtle one-off bug, hours to find.

Fix: send big IDs as strings, or use a JSON parser that supports BigInt.

Real-world API design: a slice of a real spec

Here's how a well-designed user resource might look:

# List
GET /api/users?limit=20&cursor=...
→ 200 OK
{
  "data": [{...}, {...}],
  "nextCursor": "abc123"
}
 
# Read one
GET /api/users/42
→ 200 OK
{"id": 42,

Notice:

• Pagination uses limit + cursor, not page numbers.
• Create returns 201 and a Location header pointing at the new resource.
• Delete returns 204 (no body).
• Errors would be 4xx with a body explaining what went wrong.

Common mistakes

Production · Performance · Security notes

Production. Version your API from day one. /api/v1/.... When you need to break a contract, you'll have somewhere to land.

Performance. Return only what the client needs. A GET /users/42 shouldn't return their entire order history.

Security. Field-level authorization matters. A logged-in user shouldn't see other users' emails just because they ask GET /users/123. Decide what's public per-field, not per-endpoint.

Exercises

1. Beginner. Browse https://docs.github.com/en/rest. Find five GET endpoints and call them with curl.
2. Beginner. Take an existing non-REST URL (e.g. /api/getAllUsers) and rewrite it as REST.
3. Intermediate. Design a small REST API for a library: books, authors, loans. Sketch every URL.
4. Intermediate. Find a JSON response in a real product. Identify one field where the data type is questionable.
5. Advanced. Compare GitHub's REST API to its GraphQL API for the same query (fetch a user's repos). Note which is shorter, which is faster.

Interview questions

Beginner. What's the difference between PUT and PATCH? PUT replaces the whole resource; PATCH modifies parts.

Senior. When would you choose GraphQL over REST? When clients need many different shapes of the same data and you want to avoid over- or under-fetching. Cost is complexity.

Summary

An API is a published contract. REST is the dominant style on the web: resources as nouns, HTTP methods as verbs, JSON as the wire format, status codes as the outcome. Design URLs by resource, version from day one, and you'll have an API that lasts decades.

Quick recall

• API — a contract of URLs + rules.
• REST — nouns in URLs, verbs in HTTP method, JSON as format.
• JSON — strings, numbers, booleans, null, objects, arrays. No comments, no trailing commas, no dates.
• Verbs in URL = anti-pattern.
• Cursor pagination beats page-numbers at scale.

Quiz

1. What does "API" stand for?
2. What's wrong with the URL /api/getUserById?id=42?
3. Why send bigint IDs as strings in JSON?
4. Which HTTP method should DELETE use?
5. What's the right status code for a successful resource creation?