4.5.6 · HinglishSoftware Engineering

REST API design — resources, HTTP methods, status codes, versioning, pagination

2,470 words11 min readRead in English

4.5.6 · Coding › Software Engineering


REST KYA hai? (first principles)

REST = REpresentational State Transfer. Har cheez ke liye custom function banana (getUser, deleteUserById, updateUserEmail...) ki jagah, REST kehta hai:

  • Apne domain ko resources ke roop mein model karo (ek user, ek order, ek comment).
  • Har resource ka ek stable URI (address) hota hai, jaise /users/42.
  • Aap us resource ki state ki representations (JSON, usually) aage-peeche transfer karte ho.
  • Verb (aap kya karna chahte ho) HTTP method mein rehta hai, URL mein nahi.

HTTP Methods (the verbs)

Do properties jo sahi design drive karti hain:


Status Codes (server ka reply)

Pehla digit ek class hai; classes yaad karo, phir famous members.

Figure — REST API design — resources, HTTP methods, status codes, versioning, pagination

Versioning (WHY aur HOW)


Pagination (WHY aur HOW)


Worked end-to-end examples


Flashcards

REST ka matlab kya hai aur uska core idea kya hai?
Representational State Transfer — domain ko resources (nouns) ke roop mein model karo jo URIs se address kiye jaate hain, ek chhote fixed set of HTTP methods (verbs) se act kiya jaata hai, state representations (JSON) transfer karte hue.
RESTful URL mein verb kahan jaata hai, jaise user 42 delete karna?
HTTP method mein (DELETE /users/42), URL mein NAHI. URLs resources ke naam hote hain, kabhi actions nahi jaise /deleteUser.
"Safe" vs "idempotent" HTTP methods define karo.
Safe = server-state change nahi (GET). Idempotent = N calls ek call ki tarah same final state dete hain (GET, PUT, DELETE). POST dono nahi hai.
POST idempotent kyun nahi hai aur retries ke liye yeh kyun matter karta hai?
Har POST ek naya resource create karta hai, toh timeout ke baad retry karne se duplicates ban sakte hain (jaise double charge). Known id pe PUT/DELETE retry karna safe hai.
PUT aur PATCH mein fark?
PUT = full replace (omit ki gayi fields wipe/default ho jaati hain); PATCH = partial merge (omit ki gayi fields unchanged rehti hain).
Resource create karne wale successful POST ke liye kaunsa status code, aur kaunsa header?
201 Created, saath mein ek Location: header jo naye resource ka URI deta hai.
Body-less successful DELETE ke liye kaunsa status code?
204 No Content.
401 aur 403 mein fark?
401 = authenticated nahi (aap kaun ho? log in karo / token bhejo). 403 = authenticated ho lekin permitted nahi.
First digits 2xx/3xx/4xx/5xx ka matlab kya hai?
2xx success, 3xx redirect, 4xx client error, 5xx server error.
409 Conflict kab use karte hain?
Jab request current state se clash kare — jaise duplicate unique field, edit version mismatch.
Teen API versioning strategies batao.
URI (/v1/users), header (Accept: vnd.app.v2+json), query param (?version=2).
Breaking vs non-breaking API change kya hoti hai?
Breaking: field remove/rename karna, type badalna, optional ko required banana. Non-breaking (additive): naya optional field ya naya endpoint.
1-indexed page p ke liye page size L ke saath offset formula?
offset = (p-1)*L.
N items, page size L ke liye total pages, aur ceiling kyun?
ceil(N/L); final partial page of leftover rows ko abhi bhi apna page chahiye.
Offset vs cursor pagination — key tradeoff?
Offset: kisi bhi page pe jump kar sakte ho lekin live data pe unstable + deep offsets pe slow. Cursor (keyset): stable aur fast (WHERE key > cursor) lekin arbitrary page pe jump nahi kar sakte.

Recall Feynman: 12-saal ke bachche ko samjhao

Ek badi library imagine karo. Har kitaab ka apna shelf address hota hai (yahi URL hai). Aap custom orders nahi chillate jaise "GoFetchBook37" — aap kuch standard actions use karte ho: ise read karo (GET), ek naya add karo (POST), ise naye copy se swap karo (PUT), ek page fix karo (PATCH), ya bahar phenko (DELETE). Jab aap poochho, librarian ek colored card uthata hai: green = done (2xx), yellow = tumne apni request mein gadbad ki (4xx), red = librarian trip kar gaya (5xx). Library bahut badi hai, isliye wo 20 kitaabein ek baar dete hain (pagination). Aur jab wo catalog redesign karte hain, toh purana catalog (v1) khula rakhte hain taaki jo log ushe seekh chuke hain wo kho na jaayein.


Connections

  • HTTP protocol — methods, headers, aur status codes HTTP hain, REST bas unhe achhe se use karta hai.
  • Idempotency and retries — networking reliability patterns.
  • Authentication vs Authorization — 401/403 ka distinction.
  • Caching and ETags — GET safety + conditional requests ke liye If-None-Match.
  • Database indexing — keyset pagination fast kyun hai (indexed range scan).
  • GraphQL — REST ke fixed-resource model ka alternative.
  • API versioning and backward compatibility
  • OpenAPI / Swagger — upar sab kuch document karna.

Concept Map

models domain as

addressed by

split into

acts via

constrains to ~5 verbs

makes API

classified by

GET

PUT DELETE GET

PUT vs PATCH

server replies with

first digit is

REST architecture

Resources are nouns

Stable URI

Collections and Items

HTTP methods are verbs

Uniform interface

Scalable and cacheable

Safe and Idempotent

No state change

Retry-safe

Full replace vs partial merge

Status codes

2xx 3xx 4xx 5xx classes