REST APIs: How Applications Talk to Each Other

A question your phone answers in under a second

Open the IRCTC app, type in a PNR number, and tap "Check Status." Within a second or two, your phone shows you the exact coach, berth number, and whether your ticket has been confirmed. Now ask a simple question: where is that information actually stored? It is certainly not stored inside your phone. Your phone was manufactured long before you booked that ticket, and thousands of other passengers are checking thousands of other PNRs on their own phones at the same moment, all getting different, correct answers instantly. The berth allocation data lives on a computer owned by Indian Railways, sitting in a data center that could be hundreds of kilometres from you. Your phone app is a small, mostly empty shell. The real information lives elsewhere, and every time you tap "Check Status," your app has a very short, very structured conversation with that distant computer to fetch it.

That conversation — the rules for how one program asks another program for data or asks it to do something, and how the second program replies — is what this chapter is about. The specific, most widely used way of having that conversation on the modern web is called a REST API. By the end of this chapter you will be able to read a real API request and response line by line and explain exactly what each part means and why it is there.

What is an API, precisely?

API stands for Application Programming Interface. Strip away the acronym and the idea is ordinary: an API is a defined set of rules that lets one piece of software ask another piece of software for something, without needing to know how that something is produced internally.

Think about a restaurant menu card. As a customer, you don't walk into the kitchen, you don't know which gas burner the cook uses, and you don't need to know the recipe. You read the menu, which lists exactly what you're allowed to ask for ("Paneer Butter Masala", "Masala Dosa") and how to ask for it (say the name, maybe specify "less spicy"). The kitchen is free to change its recipe, replace a cook, or switch suppliers — as long as the menu's promises still hold, you, the customer, are unaffected. The menu is the interface. It hides the kitchen's internal complexity and exposes only a fixed, agreed set of things you can request.

An API plays exactly that role between two pieces of software. The IRCTC server has an enormous, complicated internal system — databases of trains, seats, passengers, payment records. The API is the fixed "menu" of requests your app is allowed to make ("give me the status for PNR 4567891234") without needing to know how Indian Railways stores or computes that answer internally. This is true for APIs in general — even a single line of code like Math.sqrt(25) is calling an API, a programming interface exposed by a math library. What makes the IRCTC example different is that the two programs are not on the same computer. Your app is running on your phone; the "kitchen" is running on a server far away. To talk across that distance, they need a common transport language. That language, for the overwhelming majority of web and mobile apps today, is HTTP, and an API built on HTTP following a specific set of design rules is what we call a REST API.

Client and server: fixing the vocabulary

Before going further, two words need to be nailed down precisely, because the rest of the chapter depends on using them correctly.

• The client is the program that initiates the conversation by asking for something. Your IRCTC app, a browser tab, a smartwatch app — all clients.
• The server is the program that listens for such requests, does the actual work (usually by reading or writing a database), and sends back an answer.

A single physical computer at IRCTC's data centre can run server software that talks to millions of different clients (millions of phones), one request at a time, without ever needing to know or remember who asked yesterday. That last property — the server not needing to remember previous conversations — turns out to be one of the defining rules of REST, and we will return to it carefully later in this chapter because it is the single most misunderstood idea in this whole topic.

The diagram below shows the shape of a single client-server exchange, using a concrete example: a to-do list app asking its server for task number 7.

Two arrows, one round trip. The client sends a request stating exactly what it wants; the server does whatever internal work is needed (here, looking up a row in its database) and sends back a response. Everything in the rest of this chapter is about the precise vocabulary and structure inside those two arrows.

HTTP: the actual language being spoken

HTTP (HyperText Transfer Protocol) is the agreed-upon format that both the request arrow and the response arrow must follow. A request has three parts:

• A method — a word that states the intent of the request (GET, POST, PUT, DELETE — explained fully in the next section).
• A URL — the address of the specific piece of data or "resource" being asked about, such as /v1/tasks/7.
• Headers, and sometimes a body — headers are small labelled facts about the request (such as Accept: application/json, meaning "please send the answer back as JSON"); the body, present only on some requests, carries actual data being sent to the server, such as the text of a new to-do item.

A response mirrors this structure:

• A status code — a three-digit number stating what happened (200 for success, 404 for "not found", and so on — covered in detail below).
• Headers — such as Content-Type: application/json, telling the client how to interpret the body that follows.
• A body — the actual data being returned, almost always formatted as JSON today.

JSON (JavaScript Object Notation) is simply a plain-text way of writing structured data using curly braces for objects, square brackets for lists, and "key": value pairs inside. It looks like this — a real, valid response body for a weather-checking app:

GET /v1/cities/mumbai/current HTTP/1.1
Host: api.weatherindia.example
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "city": "Mumbai",
  "temperature_celsius": 31,
  "condition": "Partly Cloudy",
  "humidity_percent": 78,
  "updated_at": "2026-08-12T09:15:00+05:30"
}

Read this top to bottom exactly as the two computers would. Line 1: the client's method is GET and the resource it wants is /v1/cities/mumbai/current. Line 2: Host tells the network which server to route this to — api.weatherindia.example (a placeholder address for this chapter, not a real company). Line 3: the client states it wants JSON back. Blank line: this separates the request's headers from any body — here there is none, because a GET request is only asking to read data, not send any. Then, after the round trip completes, the server's reply: status 200 OK means "understood, and here is what you asked for," the Content-Type header confirms the body is JSON, and the body itself is one JSON object — notice the outer curly braces, the five key-value pairs separated by commas, and that the last pair has no trailing comma, which is a strict JSON rule that trips up many beginners.

Turning HTTP into REST: what "RESTful" actually means

HTTP by itself is just a transport format — it says nothing about how you should organise your URLs or which method to use for what. REST (REpresentational State Transfer) is a set of design conventions layered on top of HTTP, first described in 2000 by computer scientist Roy Fielding in his doctoral dissertation. An API that follows these conventions is called "RESTful." Three conventions matter most for you to master right now:

• Resources are nouns, identified by URLs. Everything the API can give you or let you change is treated as a "resource" — a task, a city's weather, a train's PNR record — and each resource gets its own URL. A well-designed REST URL reads like /tasks/7 (the specific task with ID 7), never like /getTaskById?id=7. The verb — what you want to do to that resource — is deliberately kept out of the URL and expressed instead through the HTTP method.
• A small, fixed set of HTTP methods act as the verbs. Instead of inventing a different function name for every action (as older API styles did), REST reuses four HTTP methods to mean four standard actions, on any resource, everywhere in the API. This is covered fully in the next section.
• The server holds no memory of previous requests (statelessness). Every single request must carry, by itself, everything the server needs to understand and act on it — the server is not allowed to rely on "remembering" that this same client asked something a moment ago.

The name "REpresentational State Transfer" itself describes this: the client and server transfer representations (JSON snapshots) of a resource's state back and forth, rather than the client reaching in and manipulating the server's actual internal data structures directly.

The four verbs, traced through one real example

Take a to-do list app talking to a server at api.todoapp.example. The resource here is a "task." Four HTTP methods map onto the four fundamental things you can do to any stored data — a pattern usually called CRUD: Create, Read, Update, Delete.

GET — read data, never changes anything. To fetch the full list of tasks:

GET /v1/tasks HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json

[
  { "id": 5, "title": "Finish Physics worksheet", "done": true },
  { "id": 7, "title": "Revise Chapter 4", "done": false }
]

Notice the body is now a JSON array (square brackets), a list of task objects, because /v1/tasks refers to the whole collection, not one item.

POST — create a brand-new resource. The client sends the new task's data in the request body; it does not yet have an ID, because the server has not created it yet:

POST /v1/tasks HTTP/1.1
Content-Type: application/json

{ "title": "Practice REST API questions", "done": false }

HTTP/1.1 201 Created
Content-Type: application/json

{ "id": 8, "title": "Practice REST API questions", "done": false }

Trace this carefully: the request body has no id field — the client doesn't get to invent one. The server picks the next free ID, saves the row, and — this is important — the status code is 201 Created, not the 200 OK you saw for GET. A different status code, on purpose, to tell the client "not only did this succeed, a new resource now exists," and the response body echoes back the full saved object, ID included, so the client's app can now display it.

PUT — update an existing resource. The URL now names the specific resource being changed, /v1/tasks/7, and the body carries its new full state:

PUT /v1/tasks/7 HTTP/1.1
Content-Type: application/json

{ "title": "Revise Chapter 4", "done": true }

HTTP/1.1 200 OK
Content-Type: application/json

{ "id": 7, "title": "Revise Chapter 4", "done": true }

DELETE — remove a resource. No body is needed going in, since the URL alone fully identifies what to delete:

DELETE /v1/tasks/7 HTTP/1.1

HTTP/1.1 204 No Content

204 means "succeeded, and there is deliberately nothing to send back" — task 7 no longer exists, so there is nothing left to describe. Notice there is no body at all after this status line — an empty body is the correct, expected response, not a bug.

Across all four examples, one URL pattern repeats: /v1/tasks for the whole collection, /v1/tasks/7 for one specific item. The method changes; the resource-naming pattern does not. That consistency — the same shape of URL means the same thing regardless of which part of the API you're using — is exactly what REST calls a "uniform interface," and it's what makes a well-designed REST API predictable enough to guess correctly without reading documentation for every single endpoint.

Status codes: reading the server's verdict at a glance

The three-digit status code is grouped by its first digit, and experienced programmers read that first digit before anything else:

• 2xx — success. 200 OK (a GET/PUT succeeded), 201 Created (a POST made something new), 204 No Content (succeeded, nothing to return).
• 4xx — the client made a mistake. 400 Bad Request (the request body was malformed, e.g. broken JSON), 401 Unauthorized (you didn't prove who you are), 404 Not Found (you asked for /v1/tasks/999 and no task with that ID exists).
• 5xx — the server made a mistake. 500 Internal Server Error is the generic "something broke on our end, and it wasn't your fault" code.

This grouping matters practically: if your app gets a 4xx back, the bug is almost certainly in what your app sent; if it gets a 5xx, the bug is on the server, and re-sending the exact same request usually won't help until the server is fixed.

The misconception worth correcting carefully: what "stateless" really means

Students very commonly assume statelessness means "the app has no memory of you" — but you stay logged into your IRCTC app for days without re-entering your password every time, so how can the server have no memory? This is the misconception to unlearn precisely: statelessness does not mean the server-client relationship has no memory overall. It means the server itself does not store any memory of the conversation between requests. All the "memory" instead lives on the client, and the client must resend it, in full, with every single request.

Concretely: after you log in once, the server hands your app a small piece of text called a token. Your app stores that token on your phone. From then on, every request your app sends — including the PNR-check request — carries that token in a header, typically Authorization: Bearer <token>. The server checks the token fresh, on every single request, and never assumes "oh, this is the same person who asked a minute ago." If you switch to a different phone or clear the app's storage, that memory of you is gone, because it was never the server's memory to begin with — it was always sitting in your client.

Why design it this way on purpose? Picture IRCTC's servers again: millions of clients hitting them simultaneously, spread across many physical machines behind a "load balancer" that can route each incoming request to any available machine. If server machine #3 had to personally remember that you logged in five minutes ago, then your next request would need to be routed to that exact same machine #3 again, forever, for your whole session — a fragile, hard-to-scale design. Because every request is self-contained, any of Indian Railways' servers can handle any request from any user at any moment, which is precisely what lets the system absorb enormous, unpredictable traffic (like the exact moment Tatkal booking opens at 10 a.m.) by simply adding more identical server machines behind the scenes.

A second misconception worth naming directly: many students use "API" and "REST API" interchangeably, but they are not the same thing. Every REST API is an API, but not every API is a REST API. APIs existed long before the web — a function like Math.sqrt(25) in a programming library is an API with no network, no HTTP, and no URL involved at all. Even among web APIs, REST is only the dominant style, not the only one — you may later encounter alternatives such as GraphQL or SOAP, which solve the same "let two programs talk" problem with different rules. When this chapter (or your CBSE textbook) says "API" in a web context, it usually means REST specifically because it is overwhelmingly the most common style in practice, but the words are not strict synonyms.

Query parameters versus path segments

One last piece of URL vocabulary you will see constantly: a URL like /v1/tasks/7 uses a path segment (7) to identify exactly which resource you mean. A URL like /v1/tasks?done=false&sort=title instead uses query parameters — the part after the ?, with & separating multiple ones — to filter or modify a request over a whole collection, here asking for only the unfinished tasks, sorted by title. The rule of thumb: path segments answer "which one resource," query parameters answer "which subset, filtered or sorted how." Mixing these up is one of the most common design mistakes beginners make when they design their own first API for a school project.

Where this connects to your CBSE coursework

Class 11–12 Computer Science formally introduces networking vocabulary — protocols, HTTP, URLs, the client-server model — as part of the networking and web-technology chapters. Everything in this chapter is the concrete, working version of those definitions: when your textbook later says "HTTP is a protocol for transferring hypertext," you will already know exactly what a request and response inside that protocol look like, because you have traced several, byte by byte, above. If your school project involves fetching live data — cricket scores, weather, exam results — into a webpage or Python script, you will be calling a REST API exactly as described here: choosing a method, building a URL, reading a status code, and parsing a JSON body.

Check your understanding

• A student building a photo-sharing app wants to let users upload a new photo. Which HTTP method should the request use, and what status code should a successful response return?
• An app requests GET /v1/students/45 but no student with ID 45 exists in the database. Which status code category (2xx/4xx/5xx) should the response fall in, and which specific code fits best?
• Rewrite this poorly designed, non-RESTful URL as a proper REST URL: /deleteBook?bookId=12 — remember, the verb belongs in the HTTP method, not the URL.
• Explain, in your own words and without using the word "memory," what it means for the token-based login system described above to still be classified as "stateless" from the server's point of view.
• A weather app calls the same endpoint, GET /v1/cities/mumbai/current, twice in one minute and gets two different temperature values back, both with status 200 OK. Does this violate statelessness? Explain why or why not.
• You are designing an API for a school's library system. Write the exact request line (method + URL) you would use to: (a) list every book currently borrowed, (b) mark book ID 30 as returned, (c) add a brand-new book to the catalogue.

Summary

A REST API is the structured conversation two programs have across a network, built on HTTP. The client sends a request naming a method (GET/POST/PUT/DELETE), a URL identifying a resource, and sometimes a JSON body; the server replies with a status code (2xx success, 4xx client error, 5xx server error) and often a JSON body describing or confirming a resource's new state. REST's defining design rules are that resources are named as nouns in URLs while verbs live in the HTTP method, and that the server keeps no memory of past requests between calls — any memory needed, such as your login, is carried by the client itself on every request, most often as a token in a header. This combination of a fixed vocabulary and no server-side memory is exactly what lets a system built to serve one user scale, largely unchanged, to serve millions of them simultaneously.