🖼️ See the drawing + lab 🏠 Course home 🌿 Branch on GitHub ✏️ View source

🖼️ आकृती आणि labThe drawing + lab पूर्ण पानावर उघडा ↗Open full page ↗

🗄️ धडा 03 — REST resources: फाइलिंग कपाटांतली नामे

📍 तुम्ही इथे आहात: 12 पैकी धडा 03 · मागे: lesson-02-http-anatomy · पुढे: lesson-04-json-and-schemas

📦 या ब्रँचमध्ये काय आहे

धडे 01–02, आणि त्यासोबत कोणतेही API अंदाज करता येण्याजोगे बनवणारी मांडणीची पद्धत: resources (नामे), collections, ids, आणि कोणती क्रियापदे पुन्हा करायला सुरक्षित आहेत.

🧒 5 वर्षांच्या मुलाला समजावल्यासारखे

Archive मध्ये कपाटे 🗄️ आहेत, प्रत्येक कपाटात drawers 📁 आहेत, आणि प्रत्येक drawer ला एक लेबल आहे. Counter च्या slips त्यांना तशीच नावे देतात:

/v1/students — संपूर्ण कपाट (एक collection). GET त्याची यादी देते; POST नवीन drawer जोडते.
/v1/students/2 — एक drawer (एक resource). GET तो वाचते, PUT त्यातला मजकूर पूर्ण बदलते, DELETE तो काढून टाकते.
/v1/classes/3A/students — कपाटे एकमेकांत असू शकतात: एका वर्गाचे विद्यार्थी.

हे अंदाज करण्याजोगे बनवणारा नियम: URLs म्हणजे नामे, methods म्हणजे क्रियापदे. कधीच /getStudent?id=2 किंवा /deleteStudent/2 नाही — क्रियापद आधीच method मध्ये आहे. लोक REST म्हणतात तेव्हा त्यांना हेच म्हणायचे असते.

आणि clerk ला महत्त्वाची वाटणारी आणखी एक गोष्ट: ही slip दोनदा देणे सुरक्षित आहे का?

GET — safe: वाचल्याने काहीच बदलत नाही.
PUT आणि DELETE — idempotent: दोनदा केले तरी निकाल एकदा केल्यासारखाच (दोनदा बदलले = बदलले; दोनदा काढले = तरीही गेलेले, दोन्ही वेळा 204).
POST — स्वतःहून idempotent नाही: "Zoya ला जोडा" अशा दोन slips मुळे दोन Zoya नोंदल्या जाऊ शकतात. धडा 07 पावती क्रमांकाने हे दुरुस्त करतो.

🗺️ आकृती

flowchart TB
    cab["🗄️ /v1/students — the cabinet (collection)<br/>GET lists · POST adds a drawer"]
    dr["📁 /v1/students/2 — one drawer (resource)<br/>GET reads · PUT replaces · DELETE removes"]
    nest["🧭 /v1/classes/3A/students<br/>nouns nest; no verbs in URLs"]
    cab -->|"1 pick an id"| dr
    cab -->|"2 filter by parent"| nest
    safe["🔁 safe to repeat? GET yes · PUT/DELETE twice = once · POST no (→ lesson 07)"]
    dr -.->|"3"| safe

❓ काय

Resource: ओळख आणि URL असलेली एक गोष्ट. Collection: पालक URL वरचा त्यांचा संच. Ids clients साठी अपारदर्शक असतात — ते क्रमाने आहेत असे कधीच गृहीत धरू नका (आमचे आहेत, पण फक्त वाचायला सोपे जावे म्हणून).
क्रियापदांचा अर्थ (counter काय वचन देतो): GET वाचते; POST तयार करते (उत्तर 201 + Location); PUT पूर्ण drawer बदलते; PATCH त्याचा काही भाग बदलते (आम्ही PATCH वगळतो — कल्पना तीच); DELETE काढते (उत्तर 204, आणि आधीच गेलेले असेल तरी पुन्हा 204).
Idempotent = N एकसारख्या calls नंतरचा निकाल एका call नंतरच्या निकालाइतकाच. यामुळेच client तुटलेल्या connection नंतर न घाबरता retry करू शकतो.
Nesting "कशाचे?" याचे उत्तर देते — /classes/3A/students — पण दोन पातळ्या सहसा पुरेशा असतात; त्यापेक्षा खोल झाडांऐवजी filters वापरतात (/students?class=3A, धडा 08).

🔧 PUT विरुद्ध PATCH विरुद्ध POST, आणि बाकीचे चार: counter आता सातही methods ना उत्तर देतो — PATCH /v1/students/2 {"grade":"A"} एक field बदलते, HEAD फक्त headers देते, OPTIONS काय चालते त्याची यादी देते. प्रत्येक method, तीन शब्द (safe · idempotent · cacheable) आणि त्याचे status codes यांसह, धडा 13 — प्रत्येक REST method मध्ये काढलेली आहे; bash api/methods_demo.sh चालू counter वर प्रत्येक नियम सिद्ध करते.

🤔 का

अंदाज करता येणे हेच product आहे. तुमचे API कधीच न पाहिलेला developer अंदाज करू शकतो की GET /v1/students/2 एक विद्यार्थी वाचते आणि DELETE /v1/students/2 त्याला काढते — आणि proxy, cache आणि gateway सुद्धा तसाच अंदाज करू शकतात, कारण ही पद्धत सगळ्यांची सामायिक आहे. URLs मधली क्रियापदे हे सगळे फेकून देतात आणि सगळ्यांना PDF वाचायला भाग पाडतात.

🔧 कसे (या repo मध्ये)

school_api.py मधले route() path ला नामे आणि ids मध्ये तोडते (['students', '2']); do_GET, do_POST, do_PUT, do_DELETE ही क्रियापदे आहेत. लक्षात घ्या, do_DELETE विद्यार्थी अस्तित्वात होता का ते कधीच तपासत नाही: STUDENTS.pop(sid, None) मग 204 — ही एका ओळीतली idempotency आहे.

🧪 करून पाहा

K='X-API-Key: hall-pass-123'; B=http://127.0.0.1:8080/v1
curl -s "$B/students?limit=10"                       # the cabinet
curl -s $B/students/2                                # one drawer
curl -s $B/classes/3B/students                       # nested nouns
curl -s -o /dev/null -w '%{http_code}\n' -X DELETE $B/students/5 -H "$K"   # 204
curl -s -o /dev/null -w '%{http_code}\n' -X DELETE $B/students/5 -H "$K"   # 204 again — idempotent
curl -s -X PUT $B/students/4 -H "$K" -H 'Content-Type: application/json' -d '{"name":"Meera","class":"3B","grade":"A+"}'
curl -s -X PUT $B/students/4 -H "$K" -H 'Content-Type: application/json' -d '{"name":"Meera","class":"3B","grade":"A+"}'   # same answer

✅ तपासा — तुम्हाला काय दिसायला हवे

दोन DELETE दोनदा 204 छापतात; दोन एकसारखे PUT एकसारखेच JSON परत देतात (आणि -i जोडल्यास तोच ETag). GET /v1/classes/3B/students फक्त 3B ची यादी देते. विद्यार्थी 5 परत मिळवण्यासाठी server पुन्हा सुरू करा (Ctrl+C, पुन्हा चालवा) — archive memory मध्ये आहे.

🏁 तुम्ही आत्ताच काय सिद्ध केले

फक्त नाम आणि क्रियापदावरून तुम्ही endpoint चा अर्थ ओळखू शकता, आणि तुम्ही idempotency अनुभवली: safe slip पुन्हा दिल्याने काहीच बदलले नाही.

⚠️ नेहमीच्या चुका

URLs मध्ये क्रियापदे (/createStudent) — method हेच क्रियापद आहे
स्थिती बदलणारा GET (/students/2/delete) — crawlers आणि prefetchers त्यावर "click" करतील
दुसऱ्या DELETE वर 404 परत करणे — यामुळे retries विनाकारण अयशस्वी होतात; दोनदा 204 हेच बरोबर
खोल nesting (/schools/1/classes/3A/students/2/grades/3) — दोन पातळ्यांनंतर filters वापरा

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: idempotent क्रियापदांमुळेच retries, load-balancer failover आणि "at-least-once" queues सुरक्षित होतात. तुम्ही वाचलेली प्रत्येक दुहेरी-order घटना म्हणजे चांगल्या हेतूच्या client ने retry केलेले non-idempotent write असते.

⏭️ पुढे

Slip वर काय असते? प्रमाणित form — JSON, validation, आणि छापलेला कॅटलॉग (OpenAPI).

git checkout lesson-04-json-and-schemas

🗄️ Lesson 03 — REST resources: nouns in filing cabinets

📍 You are here: Lesson 03 of 12 · Previous: lesson-02-http-anatomy · Next: lesson-04-json-and-schemas

📦 What's in this branch

Lessons 01–02, plus the filing convention that makes any API predictable: resources (nouns), collections, ids, and which verbs are safe to repeat.

🧒 Explain like I'm 5

The archive has cabinets 🗄️, each cabinet has drawers 📁, and every drawer has a label. The counter's slips name them the same way:

/v1/students — the whole cabinet (a collection). GET lists it; POST adds a new drawer.
/v1/students/2 — one drawer (a resource). GET reads it, PUT replaces its contents, DELETE removes it.
/v1/classes/3A/students — cabinets can nest: the students of a class.

The rule that makes it predictable: URLs are nouns, methods are verbs. Never /getStudent?id=2 or /deleteStudent/2 — the verb is already in the method. That is what people mean by REST.

And one more thing the clerk cares about: is this slip safe to hand in twice?

GET — safe: reading changes nothing.
PUT and DELETE — idempotent: doing it twice leaves the same result as once (replace twice = replaced; delete twice = still gone, 204 both times).
POST — not idempotent by itself: two "add Zoya" slips could file two Zoyas. Lesson 07 fixes that with a receipt number.

🗺️ Diagram

flowchart TB
    cab["🗄️ /v1/students — the cabinet (collection)<br/>GET lists · POST adds a drawer"]
    dr["📁 /v1/students/2 — one drawer (resource)<br/>GET reads · PUT replaces · DELETE removes"]
    nest["🧭 /v1/classes/3A/students<br/>nouns nest; no verbs in URLs"]
    cab -->|"1 pick an id"| dr
    cab -->|"2 filter by parent"| nest
    safe["🔁 safe to repeat? GET yes · PUT/DELETE twice = once · POST no (→ lesson 07)"]
    dr -.->|"3"| safe

❓ What

Resource: a thing with an identity and a URL. Collection: a set of them at the parent URL. Ids are opaque to clients — never assume they are sequential (ours are, for readability only).
Verb semantics (what the counter promises): GET reads; POST creates (answer 201 + Location); PUT replaces the whole drawer; PATCH edits part of it (we skip PATCH — same idea); DELETE removes (answer 204, and 204 again if it was already gone).
Idempotent = the result after N identical calls equals the result after one. It is what lets a client retry on a dropped connection without fear.
Nesting answers "of what?" — /classes/3A/students — but two levels is usually enough; deeper trees get replaced by filters (/students?class=3A, lesson 08).

🔧 PUT vs PATCH vs POST, and the other four: the counter now answers all seven methods — PATCH /v1/students/2 {"grade":"A"} changes one field, HEAD gives the headers only, OPTIONS lists what is allowed. Each is drawn, with the three words (safe · idempotent · cacheable) and its status codes, in lesson 13 — every REST method; bash api/methods_demo.sh proves every rule on the running counter.

🤔 Why

Predictability is the product. A developer who has never seen your API can guess that GET /v1/students/2 reads one student and DELETE /v1/students/2 removes it — and a proxy, a cache and a gateway can guess the same, because the convention is shared. Verbs in URLs throw that away and force everyone to read the PDF.

🔧 How (in this repo)

route() in school_api.py splits the path into nouns and ids (['students', '2']); do_GET, do_POST, do_PUT, do_DELETE are the verbs. Notice do_DELETE never checks whether the student existed: STUDENTS.pop(sid, None) then 204 — that is idempotency in one line.

🧪 Try it

K='X-API-Key: hall-pass-123'; B=http://127.0.0.1:8080/v1
curl -s "$B/students?limit=10"                       # the cabinet
curl -s $B/students/2                                # one drawer
curl -s $B/classes/3B/students                       # nested nouns
curl -s -o /dev/null -w '%{http_code}\n' -X DELETE $B/students/5 -H "$K"   # 204
curl -s -o /dev/null -w '%{http_code}\n' -X DELETE $B/students/5 -H "$K"   # 204 again — idempotent
curl -s -X PUT $B/students/4 -H "$K" -H 'Content-Type: application/json' -d '{"name":"Meera","class":"3B","grade":"A+"}'
curl -s -X PUT $B/students/4 -H "$K" -H 'Content-Type: application/json' -d '{"name":"Meera","class":"3B","grade":"A+"}'   # same answer

✅ Verify — what you should see

Two DELETEs print 204 twice; two identical PUTs return the identical JSON (and the same ETag if you add -i). GET /v1/classes/3B/students lists only 3B. Restart the server (Ctrl+C, run again) to get student 5 back — the archive is in memory.

🏁 What you just proved

You can predict an endpoint's meaning from its noun and verb alone, and you have felt idempotency: repeating a safe slip changed nothing.

⚠️ Common mistakes

verbs in URLs (/createStudent) — the method is the verb
GET that changes state (/students/2/delete) — crawlers and prefetchers will "click" it
returning 404 on the second DELETE — makes retries fail for no reason; 204 twice is correct
deep nesting (/schools/1/classes/3A/students/2/grades/3) — use filters after two levels

🏭 Why this matters in production: idempotent verbs are what make retries, load-balancer failover and "at-least-once" queues safe. Every duplicate-order incident you have read about is a non-idempotent write retried by a well-meaning client.

⏭️ Next

What goes on the slip? The standard form — JSON, validation, and the printed catalogue (OpenAPI).

git checkout lesson-04-json-and-schemas

← Previoushttp anatomy Next →json and schemas

This page is the lesson's README from the lesson-03-rest-resources branch, shown here so the whole School stays on one site. Code files open on GitHub at the same branch.