REST APIs: Building Your Digital Waiter

The Score That Wasn't On Your Phone

During an India cricket match, you open an app and see "142/3 in 18.4 overs" update within seconds of the ball being bowled. Stop and think about what actually happened there. Your phone did not watch the match. It did not calculate the score. It does not even store the score permanently — close the app for a week and reopen it, and it shows you whatever match is live now, not last week's. So where did "142/3" actually come from, and how did it travel from a stadium into your hand in under two seconds?

The answer is that your app asked another computer — one sitting in a data centre somewhere, connected to the official scoring system at the stadium — a very precise question: "What is the current score for this match?" That other computer answered back with exactly the data needed, nothing more and nothing less. This question-and-answer exchange between two computer programs, carried out according to a strict and predictable set of rules, is what this chapter is about. The set of rules is called REST, and a program built to answer these questions is called a REST API. By the end of this chapter, you will be able to read, write, and mentally trace a REST API request the same way you already trace a math word problem: step by step, with a predictable result at the end.

Two Programs, One Conversation: Client and Server

Every REST API conversation has exactly two participants, and mixing up their roles is the single most common mistake beginners make — so let us fix the vocabulary immediately.

The client is the program that starts the conversation by asking for something. Your cricket app is a client. So is your web browser when you open a website, and so is the UPI payment app on your phone when you tap "Pay ₹200."

The server is the program that owns the actual data and answers the question. The scoring system connected to the stadium is a server. Your bank's computer, the one that actually holds the number representing your account balance, is a server.

Notice something important: the client never touches the real data directly. Your cricket app does not have a live wire running into the stadium's scoreboard, and your payment app does not directly rewrite your bank balance. The client can only ask, and the server decides whether and how to answer. This separation is deliberate. It means the company running the server can change how their data is stored internally, add more machines to handle traffic, or fix an internal bug — all without breaking a single one of the millions of apps that ask it questions — as long as the format of the questions and answers stays the same.

Meet the Digital Waiter

Now picture a restaurant. You, sitting at a table, are the client — you want food, but you are not allowed to walk into the kitchen. The kitchen, with its ingredients, its stove, and its cooks, is the server — it has everything needed to produce your meal, but it cannot let dozens of customers wander in and interrupt the cooks every thirty seconds to check on their order.

Standing between you and the kitchen is the waiter. You never ask the kitchen anything directly. You tell the waiter exactly what you want, using a fixed, well-understood format — "one plate of dosa, no onions." The waiter carries that exact request to the kitchen, waits, and carries back exactly what the kitchen prepared, or, if something went wrong, carries back a clear explanation: "sorry, we're out of dosa batter."

A REST API is that waiter. It is a layer of software sitting between the client and the server's actual data, accepting requests in a fixed, predictable format, forwarding them to the server's internal systems, and returning responses in that same fixed, predictable format. The word "API" (Application Programming Interface) just means "a defined way for one program to talk to another." REST is one specific, extremely popular set of rules for how that conversation should be structured — rules we are about to unpack one at a time.

The Four Things You Can Ask a Waiter To Do

In a restaurant, there are really only four kinds of things you ever ask for, and REST APIs mirror this almost exactly using what are called HTTP methods. (HTTP is the underlying protocol, or shared language, that the request travels in — it is the "http" you see at the start of a website address.)

• GET — "show me what you have." You are reading the menu, or checking the status of an order already placed. Nothing changes. You can ask the same GET question a hundred times, and nothing on the server's side is altered.
• POST — "make me a new one." You are placing a brand-new order. Something new gets created that did not exist before — a new row in the restaurant's order book, a new record in a database.
• PUT — "replace my order with this instead." You already placed an order, and now you are changing it completely. An existing thing gets updated.
• DELETE — "cancel my order." An existing thing is removed.

Formally: GET reads, POST creates, PUT updates, and DELETE removes. Every feature you have ever used in an app — posting a photo, editing your profile name, unfollowing someone, checking your marks online — reduces to one or a combination of these four actions performed against some piece of data sitting on a server.

The Address on the Order Slip: Endpoints and Resources

When you tell the waiter what you want, you do not just say "GET" — you say what you want to GET. In a restaurant, that is a dish name. In a REST API, it is a web address called an endpoint, and it always points at a resource — REST's word for "a specific thing the server knows about," such as one student, one order, or one match.

Consider this endpoint, which we will use as a worked example for the rest of this chapter — a fictional school portal that stores student records:

https://api.schoolportal.in/students/23

Read it left to right, the way you would read a postal address: general to specific.

• https:// — talk to this server securely (the "s" means the conversation is encrypted).
• api.schoolportal.in — the specific server to talk to.
• /students — the collection: "the students resource," meaning all student records.
• /23 — one specific item inside that collection: the student whose ID is 23.

A well-designed REST endpoint reads like a sentence built from nouns, not verbs. Notice there is no word "get" or "fetch" anywhere in that address — the verb is supplied separately, by the HTTP method. GET /students/23 reads student 23. DELETE /students/23 removes student 23. POST /students — notice, no ID, because you do not know the new student's ID yet, the server will assign one — creates a brand-new student inside the collection. This is the single biggest structural idea in REST: the same address, combined with a different method, produces an entirely different action.

Tracing a Real Request, Step by Step

Let us now trace an actual GET request the way you would trace a line of code, because the sentence "the app displays the data" is quietly hiding four distinct steps.

fetch("https://api.schoolportal.in/students/23")
  .then(response => response.json())
  .then(data => console.log(data));

Step 1. The client builds the request. It has three parts: the method (GET, since we are only reading), the endpoint (/students/23), and, optionally, headers — small pieces of metadata about the request itself, such as "I can understand JSON data."

Step 2. The request travels over the internet to api.schoolportal.in. This is the waiter walking to the kitchen.

Step 3. The server's code receives the request, reads "GET, resource = students, id = 23," looks up that exact record in its database, and packages an answer.

Step 4. The server sends back a response, which always has two parts: a status code — a three-digit number summarising what happened — and a body, the actual data, almost always formatted as JSON. For our request, the response might look like this:

Status: 200 OK
{
  "id": 23,
  "name": "Ananya Sharma",
  "class": "8-B",
  "marks": { "maths": 91, "science": 88 }
}

JSON (JavaScript Object Notation) is just a text format for representing data as key-value pairs inside curly braces — "name" is a key, "Ananya Sharma" is its value. You do not need to know JavaScript to read or write JSON; it is used by nearly every REST API regardless of what programming language the server or the client happens to be written in, because both sides only need to agree on the text format, not the language.

Back in the code from Step 1: the line response.json() tells the browser "parse that JSON text body into a usable object," and the final line prints the result. Trace the whole thing end to end and the value printed to the console is exactly the object shown above, now usable as ordinary data — data.name would give you the text "Ananya Sharma", and data.marks.maths would give you the number 91.

Creating and Changing Data: POST, PUT, and DELETE in Action

GET never changes anything, but the other three methods do — and here the request needs to carry data of its own, called the request body, in addition to the method and endpoint.

fetch("https://api.schoolportal.in/students", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Rohan Verma", class: "8-B" })
});

Trace it: the method is POST, the endpoint is the collection /students — not a specific ID, since we are adding a new one — and the body carries the new student's details as a JSON string. The server creates a new record, assigns it the next available ID, say 24, and typically responds:

Status: 201 Created
{ "id": 24, "name": "Rohan Verma", "class": "8-B" }

Notice the status code is 201, not 200. This is not a random choice: 201 specifically means "your request succeeded, and as a result a new resource was created" — meaningfully more precise information than a plain "it worked" (200). A well-built REST API is precise about this distinction, and reading status codes carefully is how you will debug your own code later without guessing.

Updating that student uses PUT, pointed at the specific ID:

fetch("https://api.schoolportal.in/students/24", {
  method: "PUT",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Rohan Verma", class: "8-C" })
});

And removing that student needs no body at all, because you are not sending new data, only pointing at the thing to remove:

fetch("https://api.schoolportal.in/students/24", { method: "DELETE" });

Why You Should Never Double-Tap "Pay"

Here is a place where this chapter stops being theory and starts protecting your actual money. Suppose you are paying a friend ₹500 through a UPI app. Under the hood, that action behaves like a POST — you are asking a server to create a brand-new transaction record, not merely to read one. Now suppose the app freezes for three seconds right after you tap "Pay," and you cannot tell if it went through.

If you tap "Pay" again out of impatience, you may have just sent a second POST request, which — if the first one had actually succeeded — creates a second, separate transaction. Your friend receives ₹1000, not ₹500. This is precisely why POST is called not idempotent: sending it twice does not leave the world in the same state as sending it once. GET, PUT, and DELETE, by contrast, are considered idempotent — asking to read the same thing twice, replacing a record with the same new version twice, or deleting an already-deleted record a second time, all leave the data in the same final state as doing it once. This is exactly why, when a payment freezes, the correct move is to check your bank statement or transaction history (a safe, repeatable GET) rather than tapping "Pay" a second time.

Status Codes: What the Waiter Tells You When Things Go Wrong

A response always carries a status code, and every code falls into one of a small number of families based on its first digit. Learning these families is more useful than memorising individual numbers, because it lets you instantly judge whose "fault" a failure is — yours, as the client, or the server's.

• 2xx — Success. 200 OK (a GET or an update worked), 201 Created (a POST successfully made something new), 204 No Content (a DELETE worked, and there is nothing left to send back).
• 4xx — The client made a mistake. 400 Bad Request (the request body was malformed, for example broken JSON), 401 Unauthorized (you did not prove who you are), 404 Not Found (you asked for /students/9999 and no such student exists), 429 Too Many Requests (you asked too fast — more on this shortly).
• 5xx — The server made a mistake. 500 Internal Server Error is the server's own code for "something broke on my end while handling a perfectly valid request; it is not your fault."

This is genuinely useful for debugging: if your app breaks and the response says 404, the bug is almost certainly in the endpoint you typed — a wrong ID, a typo in the address. If it says 500, the bug is on the server, and no amount of changing your request will fix it from your side.

Correcting a Common Misconception: "REST Means the API Returns JSON"

A large number of students, and more than a few working programmers, believe an API "is RESTful" simply because it responds with JSON. This is false, and worth correcting carefully, because it confuses a data format with an architectural style.

REST does not require JSON at all. The term REST — REpresentational State Transfer — was coined by computer scientist Roy Fielding in his year-2000 doctoral dissertation at the University of California, Irvine, written before JSON was in common use; REST APIs can and do reply using other formats, such as XML. What actually makes an API "RESTful" is a set of architectural rules being followed:

• Everything is modelled as a resource, addressed by a stable URL such as /students/23, rather than as a remote function call.
• The standard HTTP methods are used with their proper, agreed-upon meanings — a GET must never change data, no matter how convenient that might seem.
• Each request must be stateless: it must carry every piece of information the server needs to handle it, such as an authentication token proving who you are, because the server does not remember anything about your previous requests. Send two GET requests in a row, and the server treats them as two completely unrelated strangers walking up to the counter — it has no memory of the first one while handling the second.

JSON is simply the most popular choice of data format for the body of a request or response, because it is compact and easy for nearly every programming language to read. Choosing JSON is a convenience. It is not a rule of REST itself.

A Second Misconception: "A GET Request Is Always Harmless to Repeat"

Because GET is defined as read-only, it should never modify data — but this is a rule the API's programmer must deliberately follow; nothing in the internet itself automatically enforces it. Browsers, search engines, and caching systems all assume GET is safe to repeat freely — a search engine, for instance, sends GET requests to the same links again and again while indexing the web. A poorly written server that secretly changes data inside a GET handler (say, one that increments a "view count" and calls that harmless, or worse, deletes something) creates a well-documented, genuinely dangerous category of bug, precisely because every other system on the internet assumes GET requests are free to repeat without consequence. The lesson: the meanings of the four methods and the rule of statelessness are conventions that everyone building REST APIs agrees to follow, not laws of physics enforced automatically — which is exactly why understanding them, rather than only memorising them, matters.

Worked Problem: Rate Limits, in Arithmetic

A server cannot answer unlimited questions from one client, or a single careless app could overwhelm it. Nearly every real API therefore enforces a rate limit — a maximum number of requests allowed within a fixed time window — and returns 429 Too Many Requests once a client crosses it.

Suppose the school portal's documentation states: "Maximum 300 requests per hour, per app." Let us turn that sentence into the numbers a programmer actually needs before writing any code.

• Requests allowed per minute = 300 requests ÷ 60 minutes = 5 requests per minute.
• If your app automatically refreshes a student's live attendance status, the safe refresh interval is at least 60 seconds ÷ 5 = 12 seconds between requests, to stay comfortably under the limit.
• Now suppose your app is careless instead, and sends one request every 5 seconds. In one hour, that is 3600 seconds ÷ 5 seconds = 720 requests — more than double the allowed 300. The app crosses the limit exactly at its 300th request, which happens at 300 × 5 = 1500 seconds into the hour, or 25 minutes in. From that point on, every further request in that hour receives 429 Too Many Requests instead of real data, until the hour resets.

This is exactly the kind of calculation a REST API's documentation expects a programmer to be able to do before writing a single line of code, and it is the same "rate × time" arithmetic you already use for speed and distance problems, applied here to a server instead of a moving object.

Putting the Whole Conversation on One Diagram

Here is the entire GET request from earlier, drawn as a single conversation in four numbered steps: the request going out, the API forwarding it, the server answering, and the response coming back.

Notice that the diagram has two separate "lanes": the top lane (steps 1 and 2) carries the request further and further away from you, while the bottom lane (steps 3 and 4) carries the response back. The API box in the middle is the only part of the system that ever talks to both the client and the server — the client never sees the database, and the server never talks to your phone directly. That single fact is the entire reason REST APIs exist: they let one side change freely without breaking the other.

Try It Yourself

1. The school portal wants to let a teacher permanently remove student ID 47 from the system. Write the HTTP method and endpoint you would use, in the form METHOD /path.
2. A request to GET /students/999 comes back with status 404. Whose "fault" does this indicate — the client's or the server's — and what specifically probably went wrong?
3. A different request to GET /students/23 comes back with status 500. Is this the same kind of problem as question 2? Explain the difference in one or two sentences.
4. An API's documentation says: "Maximum 120 requests per hour." On average, how many seconds must you wait between requests to stay safely under that limit forever? Show the division.
5. True or false, with a one-sentence reason: "A well-designed REST API's GET request is always safe to send twice in a row." Then do the same for POST.
6. A classmate says, "This app must be a REST API because it sends back JSON." Using what you learned in this chapter, explain precisely why that reasoning is incomplete, and name one thing you would actually need to check instead.

Summary

A REST API is software that sits between a client (the program asking for something, like a phone app) and a server (the program that owns the real data), forwarding requests and returning responses in a fixed, predictable format — exactly the role a waiter plays between a customer and a kitchen. Every request is built from a method, which states the intent (GET reads, POST creates, PUT updates, DELETE removes), and an endpoint, a URL that names the specific resource being acted on, such as /students/23. Every response carries a status code, whose first digit tells you the outcome's family — 2xx success, 4xx your mistake, 5xx the server's mistake — followed by a data body, almost always written in JSON. A request must be stateless, carrying everything the server needs to understand it on its own, because the server keeps no memory of previous requests. GET, PUT, and DELETE are idempotent — repeating them leaves things in the same state as doing them once — while POST is not, which is precisely why re-tapping "Pay" on a frozen UPI screen can create a second, unwanted transaction. Being "RESTful" is about following this architecture of resources, methods, and statelessness — not about which data format the response happens to use.

Practice Exercises

Now it is time to practice! Complete these challenges to solidify your understanding:

• Exercise 1: Write a short program that demonstrates the core concept from this chapter. Test it with at least 3 different inputs.
• Exercise 2: Find a real-world example where rest apis: building your digital waiter is used in an Indian company (like TCS, Infosys, Flipkart, or ISRO). Write a paragraph explaining the connection.
• Exercise 3: Create a mind-map connecting rest apis: building your digital waiter to at least 3 other topics you have studied.