🔬 धडा 05 — API बांधा: ~235 प्रामाणिक ओळींतले काउंटर

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

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

धडे 01–04, आणि त्यासोबत खऱ्या counter चे मार्गदर्शित वाचन — api/school_api.py — आणि त्यात तुमची पहिली भर.

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

Counter बांधणे हे framework चे काम वाटते, जोपर्यंत तुम्ही एक उघडून पाहत नाही. आमच्या counter चे नेमके चार भाग आहेत, file मध्ये वरून खाली:

टेबलांचा नकाशा 🧭 — routes: route() /v1/students/2 चे ['students', '2'] करते, आणि do_GET / do_POST / do_PUT / do_DELETE slip कोणत्या drawer बद्दल आहे ते ठरवतात.
तपासण्या ✅ — validate_student() (form, धडा 04) आणि authorized() (pass, धडा 06). कोणतेही काम करण्याच्या आधी नम्रपणे नकार द्या.
Archive 🗄️ — STUDENTS, एक dict. आज ते memory मध्ये आहे; Database school ते टिकाऊ बनवते. Counter ला त्याची पर्वा नसते.
Plumbing 🔧 — send() प्रत्येक शिक्का त्याच headers सह लिहिते (X-API-Version, X-Request-Id, Content-Type); error() प्रत्येक नकार एकाच आकारात लिहिते; log_line() प्रत्येक slip साठी एक ओळ छापते; rate_limited() म्हणजे रांग (धडा 10).

हाच server आहे. Frameworks तुम्हाला decorators, typed models, docs generators आणि async देतात — खऱ्या कामासाठी ते वापरा — पण ते हेच चार भाग automate करत असतात, आणि आता तुम्ही ते भाग पाहिले आहेत.

🗺️ आकृती

flowchart TB
    subgraph file["api/school_api.py — the four parts"]
        r["1 🧭 routes: route() + do_GET/POST/PUT/DELETE"]
        c["2 ✅ checks: validate_student() · authorized()"]
        s["3 🗄️ archive: STUDENTS (a dict — for now)"]
        p["4 🔧 plumbing: send() · error() · log_line() · rate_limited()"]
    end
    client["🧑 any HTTP client"]
    client <-->|"HTTP"| p
    p --> r --> c --> s

📖 या ओळी वाचा (म्हणजे तुम्ही हरवणार नाही)

validate_student — भाग 2, form
class Handler → send, error, log_line — भाग 4, शिक्के
rate_limited, authorized, read_json — भाग 2/4, द्वारपाल
route आणि चार do_* methods — भाग 1, टेबलांचा नकाशा
list_students — धडा 08 इथे राहतो
notify — धडा 11 चा callback

❓ काय (चोरण्यासारखे तपशील)

लवकर, क्रमाने नकार द्या: rate limit → path → auth → media type → JSON → validation → काम. प्रत्येक तपासणी स्वस्त आहे आणि प्रत्येकीचा स्वतःचा status code आहे.
एकच send() म्हणजे प्रत्येक response वर तेच headers — फक्त request id सुद्धा तुमचे तासन्तास वाचवेल (धडा 12).
ThreadingHTTPServer slips एकाच वेळी हाताळतो; धड्यासाठी dict पुरेसा सुरक्षित आहे, आणि खरा database नेमका याचीच जागा घेतो.
Status codes म्हणजे निर्णय: create वर 201 + Location, delete वर 204, न बदललेल्या ETag वर 304 — प्रत्येक एक अशी ओळ आहे जिच्याकडे तुम्ही बोट दाखवू शकता.
Secrets environment मधून येतात (SCHOOL_API_KEY), code मधून किंवा URL मधून कधीच नाही.

🤔 का

कारण "आम्हाला X साठी API हवे" हे प्रत्येक team मधले sprint ticket असते, आणि आता तुम्ही त्याचा प्रामाणिक अंदाज लावू शकता: plumbing एका दिवसाचे काम (framework ने तो एक तास होतो); खरे काम म्हणजे contract — नामे, forms, error चा आकार, auth model. ज्या teams हे बरोबर करतात त्या असे counters ship करतात ज्यांना call करायला इतर teams ना आवडते.

🔧 कसे + 🧪 करून पाहा — प्रत्यक्ष वाढवा

# 1) prove the baseline:
python3 api/school_api.py & sleep 1; bash api/smoke_test.sh | head -20
# 2) YOUR first endpoint — the homework cabinet. In school_api.py:
#    HOMEWORK = []                                      (part 3, next to STUDENTS)
#    in do_GET:  if p == ["homework"]: return self.send(200, {"items": HOMEWORK})
#    in do_POST: if p == ["homework"]: (authorized? read_json? require "title") → HOMEWORK.append(...); 201
# 3) restart and call it:
curl -s http://127.0.0.1:8080/v1/homework
curl -s -X POST http://127.0.0.1:8080/v1/homework -H 'X-API-Key: hall-pass-123' -H 'Content-Type: application/json' -d '{"title":"read lesson 06"}'
# 4) add the two operations to api/openapi.yaml — the catalogue must not lie

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

GET /v1/homework {"items": []} परत देते, POST तुमच्या item सह 201 देते, आणि दुसरा GET त्याची यादी दाखवतो. Key शिवायचा POST 401 परत देतो — कारण तुम्ही authorized() पुन्हा वापरले. Smoke test अजूनही pass होतो: तुम्ही बाकीच्यांना हात न लावता एक कपाट जोडले.

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

तुम्ही खरे API चारही भागांतून वाढवले — route, check, store, plumbing — आणि आधीचे contract चालूच राहिले.

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

तपासण्यांच्या आधी काम करणे (आधी dict मध्ये लिहिणे, मग validation)
स्वतःचा वेगळा error format असलेला नवीन endpoint — नेहमी self.error(...)
हाताने लिहिलेल्या responses मध्ये Content-Length / Content-Type विसरणे — तुम्ही कधीच विसरू नये म्हणूनच send() आहे
API key source file मध्ये ठेवणे

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: frameworks हे भाग decorators मागे लपवतात, जे पहाटे 3 वाजता काहीतरी बिघडेपर्यंत छान असते. चार भाग माहीत असलेले engineers framework चे stack traces नकाशासारखे वाचतात; बाकीच्यांना ते फक्त गोंगाट वाटतो.

⏭️ पुढे

कोणत्या slips कोण देऊ शकतो? Auth — keys, tokens, OAuth, आणि writes साठी हॉल पास.

git checkout lesson-06-auth

🔬 Lesson 05 — Build an API: the counter in ~235 honest lines

📍 You are here: Lesson 05 of 12 · Previous: lesson-04-json-and-schemas · Next: lesson-06-auth

📦 What's in this branch

Lessons 01–04, plus the guided read of the real counter — api/school_api.py — and your first extension to it.

🧒 Explain like I'm 5

Building a counter sounds like a framework's job, until you see one opened up. Ours has exactly four parts, top to bottom of the file:

The desk map 🧭 — routes: route() turns /v1/students/2 into ['students', '2'], and do_GET / do_POST / do_PUT / do_DELETE decide which drawer the slip is about.
The checks ✅ — validate_student() (the form, lesson 04) and authorized() (the pass, lesson 06). Refuse politely before doing any work.
The archive 🗄️ — STUDENTS, a dict. Today it is memory; the Database school makes it durable. The counter does not care.
The plumbing 🔧 — send() writes every stamp with the same headers (X-API-Version, X-Request-Id, Content-Type); error() writes every refusal in one shape; log_line() prints one line per slip; rate_limited() is the queue (lesson 10).

That is a server. Frameworks give you decorators, typed models, docs generators and async — use them for real work — but they are automating these four parts, and now you have seen the parts.

🗺️ Diagram

flowchart TB
    subgraph file["api/school_api.py — the four parts"]
        r["1 🧭 routes: route() + do_GET/POST/PUT/DELETE"]
        c["2 ✅ checks: validate_student() · authorized()"]
        s["3 🗄️ archive: STUDENTS (a dict — for now)"]
        p["4 🔧 plumbing: send() · error() · log_line() · rate_limited()"]
    end
    client["🧑 any HTTP client"]
    client <-->|"HTTP"| p
    p --> r --> c --> s

📖 Read these lines (so you don't get lost)

validate_student — part 2, the form
class Handler → send, error, log_line — part 4, the stamps
rate_limited, authorized, read_json — part 2/4, the gate keepers
route and the four do_* methods — part 1, the desk map
list_students — lesson 08 lives here
notify — lesson 11's callback

❓ What (details worth stealing)

Refuse early, in order: rate limit → path → auth → media type → JSON → validation → work. Each check is cheap and each has its own status code.
One send() means every response carries the same headers — the request id alone will save you hours (lesson 12).
ThreadingHTTPServer handles slips concurrently; the dict is safe enough for a lesson, and exactly the thing a real database replaces.
Status codes are decisions: 201 + Location on create, 204 on delete, 304 on an unchanged ETag — each one is a line you can point at.
Secrets come from the environment (SCHOOL_API_KEY), never from the code or the URL.

🤔 Why

Because "we need an API for X" is a sprint ticket in every team, and you can now estimate it honestly: the plumbing is a day (a framework makes it an hour); the real work is the contract — the nouns, the forms, the error shape, the auth model. Teams that get those right ship counters other teams enjoy calling.

🔧 How + 🧪 Try it — extend it for real

# 1) prove the baseline:
python3 api/school_api.py & sleep 1; bash api/smoke_test.sh | head -20
# 2) YOUR first endpoint — the homework cabinet. In school_api.py:
#    HOMEWORK = []                                      (part 3, next to STUDENTS)
#    in do_GET:  if p == ["homework"]: return self.send(200, {"items": HOMEWORK})
#    in do_POST: if p == ["homework"]: (authorized? read_json? require "title") → HOMEWORK.append(...); 201
# 3) restart and call it:
curl -s http://127.0.0.1:8080/v1/homework
curl -s -X POST http://127.0.0.1:8080/v1/homework -H 'X-API-Key: hall-pass-123' -H 'Content-Type: application/json' -d '{"title":"read lesson 06"}'
# 4) add the two operations to api/openapi.yaml — the catalogue must not lie

✅ Verify — what you should see

GET /v1/homework returns {"items": []}, the POST returns 201 with your item, and a second GET lists it. A POST without the key returns 401 — because you reused authorized(). The smoke test still passes: you added a cabinet without touching the others.

🏁 What you just proved

You extended a real API through all four parts — route, check, store, plumbing — and the existing contract kept working.

⚠️ Common mistakes

doing work before the checks (writing to the dict, then validating)
a new endpoint with its own error format — always self.error(...)
forgetting Content-Length / Content-Type in hand-written responses — send() exists so you never do
storing the API key in the source file

🏭 Why this matters in production: frameworks hide these parts behind decorators, which is wonderful until something is wrong at 3 AM. Engineers who know the four parts read framework stack traces as a map; the others read them as noise.

⏭️ Next

Who may hand in which slips? Auth — keys, tokens, OAuth, and the hall pass for writes.

git checkout lesson-06-auth

← Previousjson and schemas Next →auth

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