13 · 🔧 प्रत्येक REST method — सात शिक्के

भाग 3 — संपूर्ण नकाशे. धडे 13–16 हे संदर्भ धडे आहेत: या कोर्सने धडे 01–12 मध्ये बांधलेल्या एका काउंटरपलीकडे कामातल्या अभियंत्याला भेटणारे सगळे. प्रत्येकाचा site वर पूर्ण काढलेला नकाशा आणि या repo मध्ये चालवता येणारा code आहे.

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

धडे 01–13. काउंटर आता सातही REST methods ना उत्तर देतो:

api/school_api.py — do_PATCH (merge + validate), do_HEAD (फक्त headers), do_OPTIONS (Allow यादी आणि CORS preflight)
api/methods_demo.sh — काउंटरवर प्रत्येक method, प्रत्येक नियम सिद्ध करणाऱ्या headers सह
api/methods-output.txt — निरोगी run काय छापतो
🗺️ संपूर्ण नकाशा: https://school-edh.pages.dev/api/lesson-diagrams.html#l13 — प्रत्येक method चे चित्र, तक्ता, प्रत्येक method चे status codes, PUT विरुद्ध PATCH विरुद्ध POST, चुका

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

काउंटरकडे सात शिक्के आहेत. त्यातले तीन फक्त कपाटाकडे पाहतात — 📖 GET file वाचतो, 👀 HEAD file न उघडता ती आहे का ते पाहतो, ❓ OPTIONS विचारतो "मी इथे काय करू शकतो?". चार शिक्के कपाट बदलतात — ➕ POST नवीन form file करतो (आणि त्याला नंबर देतो), 🔁 PUT एक file पूर्ण नवीन file ने बदलतो, ✏️ PATCH file मधली एक ओळ बदलतो, 🗑️ DELETE file बाहेर काढतो.

तीन शब्द शिक्क्यांना वेगळे करतात. Safe: ते काही बदलते का? Idempotent: मी ते दोनदा केले तर कपाट एकदा केल्यासारखेच राहते का? Cacheable: उत्तर जपून पुन्हा वापरता येते का? तुमच्या आणि काउंटरमधले संपूर्ण internet — browsers, CDNs, proxies, retry libraries — या तीन वचनांवर विश्वास ठेवते. एक मोडले की तुम्ही सगळे एकदम मोडता.

🗺️ आकृती

flowchart LR
  subgraph safe["SAFE · changes nothing · cacheable"]
    G[GET — read it] ; H[HEAD — headers only] ; O[OPTIONS — what may I do?]
  end
  subgraph unsafe["UNSAFE · needs the hall pass"]
    P[POST — file a NEW one<br/>not idempotent] ; U[PUT — replace the whole thing<br/>idempotent] ; PA[PATCH — change part of it<br/>idempotent for merge-patch] ; D[DELETE — remove it<br/>idempotent by state]
  end
  C((the counter)) --> safe --> C
  C --> unsafe --> C

❓ काय

Method	काय करते	Safe	Idempotent	Body आत	Cacheable	यशस्वी उत्तर
GET	एक resource किंवा यादी वाचते	✅	✅	❌ (query string)	✅	200 · 304
HEAD	GET चे फक्त headers	✅	✅	❌	✅	200 · 304
OPTIONS	परवानगी असलेले methods · CORS preflight	✅	✅	❌	✅ (Max-Age)	204 · 200
POST	तयार करते · किंवा एखादी क्रिया करते	❌	❌ Idempotency-Key नसेल तर	✅	❌	201 + Location · 200 · 202
PUT	पूर्ण resource बदलते	❌	✅	✅ सगळे fields	❌	200 · 204
PATCH	resource चा एक भाग बदलते	❌	✅ merge-patch साठी	✅ फक्त बदल	❌	200 · 204
DELETE	resource काढून टाकते	❌	✅ स्थितीनुसार	❌	❌	204 · 202

TRACE आणि CONNECT RFC मध्ये आहेत; काउंटर ते जवळजवळ कधीच लागू करत नाही.

🤔 का

प्रत्येक मध्यस्थ या तीन शब्दांवर विश्वास ठेवतो. Delete करणारा GET एखादा crawler चालवून टाकतो. वाचण्यासाठी वापरलेला POST cache होऊ शकत नाही. Idempotent नसलेला PUT निरुपद्रवी retry ला बिघडलेल्या data मध्ये बदलतो. Method निवडणे म्हणजेच तुमच्या आणि तुमच्या client मधल्या प्रत्येक गोष्टीला कोणती वचने द्यायची ते निवडणे.

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

do_PATCH body साठवलेल्या student मध्ये merge करतो, merge झालेला निकाल validate करतो, आणि अनोळखी fields 400 ने नाकारतो — गुपचूप दुर्लक्ष कधीच नाही.
do_HEAD head_only लावतो आणि do_GET ला बोलावतो; send() headers लिहितो आणि body वगळतो, त्यामुळे Content-Length आणि ETag नेमके GET पाठवेल तेच असतात.
do_OPTIONS Allow आणि Access-Control-* headers सह 204 उत्तर देतो, जे browser cross-origin PUT, PATCH किंवा DELETE आधी विचारतो (UI शाळा, धडा 11).

🧪 करून पाहा

python3 api/school_api.py &
bash api/methods_demo.sh
# then by hand:
curl -I http://127.0.0.1:8080/v1/students/2                                  # HEAD: headers, no body
curl -i -X OPTIONS http://127.0.0.1:8080/v1/students/2 | grep -i allow        # what may I do here?
curl -X PATCH http://127.0.0.1:8080/v1/students/2 -H 'X-API-Key: hall-pass-123' \
     -H 'Content-Type: application/json' -d '{"grade":"A"}'                  # one field only

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

methods_demo.sh प्रत्येक method साठी एक block छापतो: GET आणि HEAD वर तोच ETag, OPTIONS वर Allow यादी, दोन POSTs मधून दोन Location headers, दोन PUTs मधून एक student, एकाच field च्या PUT साठी problems सह 400, PATCH मधून merge झालेला student, अनोळखी PATCH field साठी 400, आणि DELETE, DELETE, GET साठी 204 204 404. पूर्ण मजकूर api/methods-output.txt मध्ये आहे.

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

तुम्ही तीन शब्द तारेवर पाहिले: safe methods नी हॉल पासशिवाय उत्तर दिले, idempotent methods नी दोनदा तीच स्थिती दिली, आणि एकमेव non-idempotent method (POST) ने जुळे तयार केले — म्हणूनच धडा 07 ने Idempotency-Key जोडली.

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

URL मध्ये क्रियापद (GET /students/5/delete): आधीच आणणारा (prefetch) browser data delete करतो.
"बाकीचे तसेच ठेवणारा" अर्धवट body असलेला PUT: एका client चे सुटलेले field दुसऱ्याचा data रिकामा करते.
अनोळखी fields कडे दुर्लक्ष करणारा PATCH: grdae मधली टायपो 200 देते आणि काहीच save करत नाही.
Location header शिवाय 201; error साठी आत {"ok": false} असलेला 200.
OPTIONS विसरणे: सूचना फलकावरून होणारे प्रत्येक cross-origin write CORS error ने fail होते.

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: retry libraries idempotent methods आपोआप retry करतात आणि POST कधीच retry करत नाहीत; CDNs फक्त GET आणि HEAD cache करतात, दुसरे काहीच नाही; browsers OPTIONS ने preflight करतात. Method बरोबर निवडा आणि तिघेही आपोआप योग्य वागतात. चुकीची निवडा आणि रात्री 2 वाजता deletion serve करणाऱ्या cache चा debug करत बसाल.

⏭️ पुढे

धडा 14 — प्रत्येक authentication पद्धत: काउंटरकडे एकाच प्रकारचा हॉल पास आहे; जगात नऊ आहेत.

13 · 🔧 Every REST method — the seven stamps

Part 3 — the full maps. Lessons 13–16 are the reference lessons: everything a working engineer meets beyond the one counter this course built in lessons 01–12. Each one has a full drawn map on the site and runnable code in this repo.

📦 What's in this branch

Lessons 01–13. The counter now answers all seven REST methods:

api/school_api.py — do_PATCH (merge + validate), do_HEAD (headers only), do_OPTIONS (the Allow list and the CORS preflight)
api/methods_demo.sh — every method against the counter, with the headers that prove each rule
api/methods-output.txt — what a healthy run prints
🗺️ The full map: https://school-edh.pages.dev/api/lesson-diagrams.html#l13 — each method drawn, the matrix, the status codes per method, PUT vs PATCH vs POST, the mistakes

🧒 Explain like I'm 5

The counter has seven stamps. Three of them only look at the cabinet — 📖 GET reads a file, 👀 HEAD checks the file is there without opening it, ❓ OPTIONS asks "what may I do here?". Four of them change the cabinet — ➕ POST files a new form (and gives it a number), 🔁 PUT swaps a file for a whole new one, ✏️ PATCH changes one line on a file, 🗑️ DELETE takes a file out.

Three words tell the stamps apart. Safe: does it change anything? Idempotent: if I do it twice, is the cabinet the same as doing it once? Cacheable: may the answer be kept and reused? The whole internet between you and the counter — browsers, CDNs, proxies, retry libraries — believes those three promises. Break one and you break them all at once.

🗺️ Diagram

flowchart LR
  subgraph safe["SAFE · changes nothing · cacheable"]
    G[GET — read it] ; H[HEAD — headers only] ; O[OPTIONS — what may I do?]
  end
  subgraph unsafe["UNSAFE · needs the hall pass"]
    P[POST — file a NEW one<br/>not idempotent] ; U[PUT — replace the whole thing<br/>idempotent] ; PA[PATCH — change part of it<br/>idempotent for merge-patch] ; D[DELETE — remove it<br/>idempotent by state]
  end
  C((the counter)) --> safe --> C
  C --> unsafe --> C

❓ What

Method	Does	Safe	Idempotent	Body in	Cacheable	Happy answer
GET	read a resource or a list	✅	✅	❌ (query string)	✅	200 · 304
HEAD	GET's headers only	✅	✅	❌	✅	200 · 304
OPTIONS	allowed methods · CORS preflight	✅	✅	❌	✅ (Max-Age)	204 · 200
POST	create · or perform an action	❌	❌ unless Idempotency-Key	✅	❌	201 + Location · 200 · 202
PUT	replace the whole resource	❌	✅	✅ all fields	❌	200 · 204
PATCH	change part of the resource	❌	✅ for merge-patch	✅ the changes	❌	200 · 204
DELETE	remove the resource	❌	✅ by state	❌	❌	204 · 202

TRACE and CONNECT exist in the RFC; a counter almost never implements them.

🤔 Why

Every intermediary trusts the three words. A GET that deletes is deleted by a crawler. A POST used for reads cannot be cached. A PUT that is not idempotent turns a harmless retry into corrupted data. Choosing the method is choosing which promises you make to everything between you and your client.

🔧 How (in this repo)

do_PATCH merges the body into the stored student, validates the merged result, and refuses unknown fields with a 400 — never a silent ignore.
do_HEAD sets head_only and calls do_GET; send() writes the headers and skips the body, so Content-Length and ETag are exactly what GET would send.
do_OPTIONS answers 204 with Allow and the Access-Control-* headers, which is what a browser asks before a cross-origin PUT, PATCH or DELETE (UI school, lesson 11).

🧪 Try it

python3 api/school_api.py &
bash api/methods_demo.sh
# then by hand:
curl -I http://127.0.0.1:8080/v1/students/2                                  # HEAD: headers, no body
curl -i -X OPTIONS http://127.0.0.1:8080/v1/students/2 | grep -i allow        # what may I do here?
curl -X PATCH http://127.0.0.1:8080/v1/students/2 -H 'X-API-Key: hall-pass-123' \
     -H 'Content-Type: application/json' -d '{"grade":"A"}'                  # one field only

✅ Verify — what you should see

methods_demo.sh prints one block per method: the same ETag on GET and HEAD, an Allow list on OPTIONS, two Location headers from two POSTs, one student from two PUTs, a 400 with problems for a one-field PUT, a merged student from PATCH, a 400 for an unknown PATCH field, and 204 204 404 for DELETE, DELETE, GET. The full text is in api/methods-output.txt.

🏁 What you just proved

You watched the three words on the wire: safe methods answered without a hall pass, idempotent methods gave the same state twice, and the one non-idempotent method (POST) made twins — which is exactly why lesson 07 added the Idempotency-Key.

⚠️ Common mistakes

A verb in the URL (GET /students/5/delete): a prefetching browser deletes data.
PUT with a partial body that "keeps the rest": one client's missing field empties another's data.
PATCH that ignores unknown fields: a typo in grdae returns 200 and saves nothing.
201 without a Location header; 200 with {"ok": false} inside for an error.
Forgetting OPTIONS: every cross-origin write from the notice board fails with a CORS error.

🏭 Why this matters in production: retry libraries retry idempotent methods automatically and never retry POST; CDNs cache GET and HEAD and nothing else; browsers preflight with OPTIONS. Get the method right and all three do the right thing for free. Get it wrong and you debug a cache serving a deletion at 2 a.m.

⏭️ Next

Lesson 14 — every authentication method: the counter has one kind of hall pass; the world has nine.

← Previoustesting docs gateway Next →auth methods

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