A REST API is a fixed way for programs to talk over HTTP. URLs name things, HTTP methods say what to do with them, and status codes say what happened.

What does a 429 error mean?

It means the app sent too many requests in a short time and should slow down. A Retry-After header may say how long to wait. Asking again for a read is fine; a booking needs more care.

Module 1 · How an App Answers a Tap · Lesson 4 of 35

What is a REST API? How the app and the server agree on what to say

13 minFree System design course · Beginner to intermediateLesson 1.4By Saket Bhatnagar

Researched and drafted with AI, reviewed and edited by Saket Bhatnagar.

In short

What is a REST API? It is a fixed contract over HTTP: URLs name things, HTTP methods say what to do, and status codes say what happened.
Think of an Udupi restaurant’s order slip: a listed dish, a verb, a table number, and the kitchen’s call back.
The status code is the instruction. Answer 200 OK to everything, and the app shows success when the work failed.

Soon

Video lesson · coming soon

What is a REST API? The menu that stops false tickets

Lala, your AI mentor, will walk you through this lesson in a short animated video. Until then, everything is here to read and try.

01 A ticket for a seat that was taken
02 One booking, step by step
03 An Udupi order slip
04 Five calls, five answers
05 The same POST, sent twice
06 Next: will it hold at noon?

Saturday, match 7 of the club tournament. The phone can find SeatJaldi’s ₹1,200-a-month server now, and Arjun has written down, in one list, every call the app may make to it. Seat B07 is already booked. A second member taps Book on B07, and the app shows “Booked!” with a ticket screen.

There is no ticket. The server answered “OK”, with a small note saying the seat was taken, and the app only checked for “OK”. At the club gate, the member’s ₹299 ticket is not in the system, and Meera apologises in front of everyone.

That evening she asks, “The server knew the seat was gone. Why did the phone say Booked?” Arjun reads his code twice. The server did say the seat was gone, in a small note. The app did check the answer. So where did it go wrong?

What is a REST API?

A REST API is a fixed contract over HTTP: a list of requests the app may send and the answers it will get. Both sides agree on it first, so nobody guesses.

Keep one line in your head: an API is a menu with fixed nouns, fixed verbs and fixed answers.

Nouns: the URL names the thing, such as /matches/7/seats or /bookings.
Verbs: the request says what to do with it: read it, create one, or remove one.
Answers: the response starts with a three-digit number, such as 201 or 409, that says what happened and what to do next.

One booking on the menu, step by step

Drag to explore

One booking, step by step. The server checks that the phone is not asking too often, then checks B07. The number that comes back tells the app what to do.

You have seen this when a payment app says “Success”, but your history is empty. Behind the screen, the server sent a success code for work that failed, and the app believed it.

You have seen it when a form says “Slow down, try again in a minute” after many taps. The server answered with a “too many requests” code and a wait time, and the app obeyed.

What are HTTP methods and status codes?

The HTTP method says what the app wants done, such as GET to read or POST to create. The status code says what happened, such as 201 for created or 409 for seat taken.

The four HTTP methods SeatJaldi uses
HTTP method	What it does	Changes data?	Same effect if sent twice?
GET	Reads, such as the seat map	No	Yes
POST	Creates, such as a booking	Yes	No, it may create two
PUT	Replaces one thing with a new copy	Yes	Yes
DELETE	Removes one thing	Yes	Yes

The kitchen’s call “busy, ask again in 30 seconds” has an HTTP version too, with three new terms.

Try it yourselfRead the menu and the replies, one call at a timeStep through five calls to SeatJaldi’s API and see what the app does after each response.

It can go wrong either way: a second booking, or a 409 for a booking that already worked.

Reading the seat map twice changes nothing, and cancelling BK-10421 twice leaves it cancelled. Creating a booking twice is different, so POST is not idempotent. A later lesson fixes this.

What is an API endpoint?

An API endpoint is the same idea as the endpoint in lesson 3, one address that does one job: here, one URL together with the HTTP method you call it with, such as GET /matches/7/seats. On Shalini’s slip, it is one dish plus one verb.

Wrong and right endpoint names: cover the Right column and fix each one first
Wrong	Right	Why
GET /getSeats	GET /matches/7/seats	The method already says get
POST /bookSeat	POST /bookings	The noun is bookings; POST creates one
GET /deleteBooking?id=BK-10421	DELETE /bookings/BK-10421	A GET must never change data

HTTP is stateless. Each request names the match, the seat and the member, so no request leans on the one before. The bookings still live in the database; stateless is about requests, not stored data. Shalini’s kitchen, too, reads only the slip in front of it.

Long lists come back in pages, as in /matches?page=2. APIs also carry a version, as in /v1/bookings, so old apps keep working.

How do you design API responses an app can trust?

Use the right HTTP method, the right status class and an error body the app can read. The first digit sets the class, and a client must act on it even for a code it has never seen.

For errors, the standard called problem details has the label application/problem+json and the fields type, title, status and detail. The app decides from the status code and type, and shows the title to the person.

javascript

async function bookSeat(matchId, seatCode, triesLeft = 1) {
  const res = await fetch("/bookings", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ match_id: matchId, seat_code: seatCode }),
  });
  // Decide from the status code, never from the body text.
  if (res.status === 201) return res.headers.get("Location");
  if (res.status === 409) throw new Error("seat taken");
  if (res.status === 429 && triesLeft > 0) {
    const h = res.headers.get("Retry-After") ?? "";
    const wait = /^\d+$/.test(h) ? Number(h) : 30;
    await new Promise((done) => setTimeout(done, wait * 1000));
    return bookSeat(matchId, seatCode, triesLeft - 1);
  }
  if (res.ok || res.status >= 500) throw new Error("check My bookings first");
  throw new Error("try again later");
}

What just happened? The app chose its next step from res.status alone. A 201 returns the booking’s address, even with no body. A 409 stops; a 5xx or any other success sends the member to My bookings. A 429 waits as told, even 0 seconds, and tries once. That is safe only because SeatJaldi’s server counts requests before it touches a booking, so its 429 means nothing was booked.

Pick a small app
Picture an ordering app for Shalini’s restaurant with three nouns: menus, orders and tables.
Write four endpoints
Write an HTTP method plus a URL for: see today’s menu, place an order, change an order’s quantity, cancel an order.
Add codes and a label
Give each one a success code and a failure code, such as 201 and 409. Mark it idempotent or not, and say what goes wrong if it is sent twice.
Check your answer
Every URL is a noun, never /placeOrder. Only POST is not idempotent. A repeated cancel ends in the same place.

Back to the club gate. Arjun’s first server answered “OK” to everything, like a kitchen that calls “coming” for a finished dish.

The next member who taps a taken seat now sees “Seat taken, pick another”. The old server put the truth in a note and the wrong number on top, and the app, rightly, trusts the number.

The API works for 100 people. Meera’s real question: will it hold when the stadium final opens at noon? Before any numbers, what exactly must it do?

Check yourself

The response to a booking was lost, so the app sends the same POST /bookings twice. What could happen?

Pick an answer to see why it is right or wrong.

Check yourself

Arjun’s server answers 200, with “ok: false” in the body, when a seat is taken. What is wrong?

Pick an answer to see why it is right or wrong.

Try it yourselfModule recap: lessons 1 to 4Five quick scenarios from the whole module. Tap an answer and read why.

Remember these three

An API is a menu: fixed nouns in the URL, fixed verbs as HTTP methods, fixed answers as status codes.
The status code is the instruction: 2xx show it, 4xx change or wait, 5xx tell the user.
POST is not idempotent, so a repeated POST may book twice.

Questions people ask

What is a REST API?: A REST API is a fixed way for programs to talk over HTTP. URLs name things, HTTP methods say what to do with them, and status codes say what happened.
What is an API endpoint?: An API endpoint is one URL plus the HTTP method you call it with, such as GET /matches/7/seats. Good URLs are nouns, like /bookings, and the method carries the action.
What does a 429 error mean?: It means the app sent too many requests in a short time and should slow down. A Retry-After header may say how long to wait. Asking again for a read is fine; a booking needs more care.

What is a REST API?

What are HTTP methods and status codes?

What is an API endpoint?

How do you design API responses an app can trust?

Check yourself

Questions people ask

Sources and further reading