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

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

🏢 धडा 01 — APIs का: फ्रंट ऑफिस

📍 तुम्ही इथे आहात: 12 पैकी धडा 01 · पुढे: lesson-02-http-anatomy

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

APIs कोणती समस्या सोडवण्यासाठी असतात — आणि ती एक कल्पना (counter वरचे contract) जी या कोर्समधल्या पुढच्या प्रत्येक design निर्णयाचे कारण सांगते. पूर्ण कोर्सभर तुम्ही वापराल अशा खऱ्या files:

api/school_api.py — फ्रंट ऑफिस: खरे HTTP/JSON API, ~235 ओळी, शून्य dependencies
api/smoke_test.sh — संपूर्ण कोर्स एका curl script मध्ये
api/api_types.py — तेच data सहा API आकारांत (पाहा प्रत्येक API प्रकार हे पान)

🎒 सुरू करण्याआधी: तुम्हाला फक्त Python 3 आणि curl लागतात, बाकी काही नाही. ही शाळा एक छोटे खरे API चालवून कल्पना शिकवते; frameworks (FastAPI, Express, Spring) तुम्ही इथे वाचणार असलेले भाग automate करतात. चांगले शेजारी: Database school (या counter मागची नोंदींची खोली) आणि UI school (त्याला call करणारा सूचना फलक).

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

शाळेच्या दप्तरखान्याची (archive) कल्पना करा 🗄️ — प्रत्येक नोंदवही, प्रत्येक grade, प्रत्येक वेळापत्रक. जुन्या वाईट दिवसांत, ज्याला काही हवे असेल तो थेट archive मध्ये जायचा आणि drawers उघडायचा: खेळाच्या शिक्षिका, canteen app, पालकांचे portal, प्रत्येकाची गोष्टी कुठे आहेत याची स्वतःची कल्पना. Drawers पुन्हा पुन्हा हलवले जायचे; कोणी काय नेले याची नोंद नसायची; archive ने एक कपाट हलवले की एकाच सकाळी तीन apps बिघडायचे.

म्हणून शाळेने counter असलेले फ्रंट ऑफिस 🏢 बांधले. आता तुम्ही archive मध्ये जात नाही. तुम्ही प्रमाणित चिठ्ठी (slip) भरता ("विद्यार्थी 2 चा grade, कृपया"), एक कारकून (clerk) ती तपासतो, उत्तर आणतो, आणि ते शिक्का मारून परत देतो ("हे घ्या — 200") किंवा कारणासह नकार देतो ("असा विद्यार्थी नाही — 404"). Slip चा नमुना सूचना दिल्याशिवाय कधीच बदलत नाही; तुम्ही शिक्षिका आहात, phone app आहात की robot, याची clerk ला पर्वा नसते.

तो counter म्हणजे API (application programming interface). Slips म्हणजे requests, शिक्का मारलेली उत्तरे म्हणजे responses, आणि कोणत्या slips आहेत व त्या काय परत देतात याचे छापलेले नियम म्हणजे contract. इथून पुढचा प्रत्येक धडा एक चांगला counter design करण्याबद्दल आहे.

🗺️ आकृती

flowchart LR
    subgraph before["🚪 before: everyone in the archive"]
        a1["sports app opens drawer 3"]
        a2["canteen app opens drawer 3 differently"]
        a3["portal opens… the drawer moved 💥"]
    end
    subgraph after["🏢 after: the front office"]
        slip["📨 1 a standard slip (request)"]
        clerk["🧑‍💼 2 the clerk checks + fetches"]
        stamp["📮 3 a stamped answer (response)"]
        slip --> clerk --> stamp
    end
    before -->|"put a counter in front"| after

❓ काय

API = counter वरचे contract: कोणत्या slips आहेत (endpoints), त्यावर काय लिहायचे (parameters, body), परत काय येते (status + body).
HTTP म्हणजे ज्या कागदावर slips लिहिल्या जातात तो — धडा 02. REST म्हणजे कपाटांची मांडणी करण्याची पद्धत — धडा 03. JSON म्हणजे form ची रचना — धडा 04.
तोच counter प्रत्येक पाहुण्याला सेवा देतो: web page, phone app, दुसरा server, AI agent (MCP school: MCP servers बहुतेक वेळा नेमक्या अशाच API समोरचे पातळ दर्शनी भाग असतात).
Counter मागे archive आहे — एक database (Database school). पाहुण्यांना त्यापासून बाहेर ठेवणे हे counter चे काम आहे.

🤔 का

कारण "app ला थेट database वाचू द्या" हा software मधला सर्वात महागडा shortcut आहे: प्रत्येक वापरकर्ता storage च्या रचनेशी बांधला जातो, प्रत्येक schema बदल म्हणजे सर्वांना एकत्र बंद ठेवावे लागणारे outage, आणि permission तपासणी, rate limits, validation किंवा logs ठेवायला जागाच उरत नाही. या सगळ्या गोष्टी counter वरच राहतात. Counter शिका आणि तुम्ही जगातले कोणतेही API वाचू शकाल — सगळी फक्त slips आणि शिक्के आहेत.

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

Counter म्हणजे api/school_api.py. ते पाच विद्यार्थी memory मध्ये ठेवते (सध्या तेच archive) आणि त्यांच्याबद्दलच्या slips ना उत्तर देते. तुम्ही ते पूर्ण धडा 05 मध्ये वाचाल; आज फक्त चालवायचे.

🧪 करून पाहा (60 सेकंद — संपूर्ण कोर्स, live)

python3 api/school_api.py          # terminal 1: the office opens on :8080
bash api/smoke_test.sh             # terminal 2: every slip and stamp in the course

तुम्हाला असे दिसायला हवे (छाटलेले):

── L02 · GET a student (200 + ETag)
HTTP/1.0 200 OK
{"id": 2, "name": "Katrina", "class": "3A", "grade": "A+"}
── L02 · unknown id (404, one error shape)
{"error": {"code": "not_found", "message": "No student with id 99."}}
── L06 · write without a hall pass (401)
{"error": {"code": "unauthenticated", "message": "Writes need an X-API-Key header.", …}}
── L07 · create with an Idempotency-Key (201) … same key again → Idempotent-Replay: true
── L08 · page 1 then page 2 (cursor) …
── L10 · 40 quick requests → the queue says 429
200 200 … 429 429 429

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

Terminal 1 प्रत्येक slip साठी एक log ओळ छापतो (GET /v1/students/2 → 200 · 1 ms · <id>); terminal 2 च्या शेवटी 200 ची रांग 429 मध्ये बदलताना दिसते. कोणतेही stack traces नाहीत. Port 8080 व्यस्त असेल तर python3 api/school_api.py 8081 ने सुरू करा आणि smoke test मधला B= बदला.

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

खरे API म्हणजे जादू नाही: कोणतीही library नसलेल्या एका Python file ने हा कोर्स शिकवणार असलेल्या प्रत्येक प्रकारच्या slip ला उत्तर दिले — आणि तुम्ही त्याची उत्तरे डोळ्यांनी वाचलीत.

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

server सुरू नसताना smoke test चालवणे — curl: (7) Failed to connect म्हणजे terminal 1 चालू नाही
http://localhost:8080/students ला call करणे — हे office /v1/ खाली राहते; 404 ची body तुम्हाला तसे सांगते
API म्हणजेच database आहे असे समजणे — ते त्यासमोरचा counter आहे

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: तुम्हाला भेटणारी प्रत्येक system — payments, maps, तुमच्या कंपनीच्या स्वतःच्या services — म्हणजे counters चा संच आहे. जी teams counter ला product म्हणून वागवतात (documented, versioned, सुरक्षित, निरीक्षणाखाली) त्या, एकमेकांच्या drawers मध्ये उचकापाचक करणाऱ्या apps असलेल्या teams पेक्षा जलद ship करतात.

⏭️ पुढे

Slip आणि शिक्क्यावर नेमके काय लिहिलेले असते? HTTP ची रचना — method, path, headers, body, status.

git checkout lesson-02-http-anatomy

🏢 Lesson 01 — Why APIs: the front office

📍 You are here: Lesson 01 of 12 · Next: lesson-02-http-anatomy

📦 What's in this branch

The problem APIs exist to solve — and the one idea (a contract at a counter) that explains every design choice in the rest of the course. Real files you will use all the way through:

api/school_api.py — the front office: a real HTTP/JSON API, ~235 lines, zero dependencies
api/smoke_test.sh — the whole course as a curl script
api/api_types.py — the same data as six API shapes (see the every API type page)

🎒 Before you start: you need Python 3 and curl, nothing else. This school teaches the ideas by running a tiny real API; frameworks (FastAPI, Express, Spring) automate the parts you will read here. Good neighbours: the Database school (the record room behind this counter) and the UI school (the notice board that calls it).

🧒 Explain like I'm 5

Imagine the school archive 🗄️ — every register, every grade, every timetable. In the bad old days, anyone who needed something walked into the archive and opened drawers: the sports teacher, the canteen app, the parents' portal, each with its own idea of where things were. Drawers got rearranged; nobody logged who took what; when the archive moved a shelf, three apps broke on the same morning.

So the school built a front office 🏢 with a counter. You do not enter the archive any more. You fill in a standard slip ("student 2's grade, please"), a clerk checks it, fetches the answer, and hands it back stamped ("here you are — 200") or refused with a reason ("no such student — 404"). The slip format never changes without notice; the clerk does not care whether you are a teacher, a phone app or a robot.

That counter is an API (application programming interface). The slips are requests, the stamped answers are responses, and the printed rules of what slips exist and what they return are the contract. Every lesson from here is about designing a good counter.

🗺️ Diagram

flowchart LR
    subgraph before["🚪 before: everyone in the archive"]
        a1["sports app opens drawer 3"]
        a2["canteen app opens drawer 3 differently"]
        a3["portal opens… the drawer moved 💥"]
    end
    subgraph after["🏢 after: the front office"]
        slip["📨 1 a standard slip (request)"]
        clerk["🧑‍💼 2 the clerk checks + fetches"]
        stamp["📮 3 a stamped answer (response)"]
        slip --> clerk --> stamp
    end
    before -->|"put a counter in front"| after

❓ What

API = the contract at the counter: which slips exist (endpoints), what goes on them (parameters, body), what comes back (status + body).
HTTP is the paper the slips are written on — lesson 02. REST is the filing convention for the cabinets — lesson 03. JSON is the form layout — lesson 04.
The same counter serves every visitor: a web page, a phone app, another server, an AI agent (MCP school: MCP servers are often thin fronts over exactly this kind of API).
Behind the counter is the archive — a database (Database school). The counter's job is to keep visitors out of it.

🤔 Why

Because "just let the app read the database" is the most expensive shortcut in software: every consumer couples to the storage layout, every schema change is a coordinated outage, and there is no place to put permission checks, rate limits, validation or logs. The counter is where all of those live. Learn the counter and you can read any API in the world — they are all slips and stamps.

🔧 How (in this repo)

The counter is api/school_api.py. It keeps five students in memory (the archive, for now) and answers slips about them. You will read all of it in lesson 05; today you only run it.

🧪 Try it (60 seconds — the whole course, live)

python3 api/school_api.py          # terminal 1: the office opens on :8080
bash api/smoke_test.sh             # terminal 2: every slip and stamp in the course

You should see, trimmed:

── L02 · GET a student (200 + ETag)
HTTP/1.0 200 OK
{"id": 2, "name": "Katrina", "class": "3A", "grade": "A+"}
── L02 · unknown id (404, one error shape)
{"error": {"code": "not_found", "message": "No student with id 99."}}
── L06 · write without a hall pass (401)
{"error": {"code": "unauthenticated", "message": "Writes need an X-API-Key header.", …}}
── L07 · create with an Idempotency-Key (201) … same key again → Idempotent-Replay: true
── L08 · page 1 then page 2 (cursor) …
── L10 · 40 quick requests → the queue says 429
200 200 … 429 429 429

✅ Verify — what you should see

Terminal 1 prints one log line per slip (GET /v1/students/2 → 200 · 1 ms · <id>); terminal 2 ends with a row of 200s turning into 429s. No stack traces. If port 8080 is busy, start with python3 api/school_api.py 8081 and edit B= in the smoke test.

🏁 What you just proved

A real API is not magic: one Python file with no libraries answered every kind of slip this course will teach — and you read its answers by eye.

⚠️ Common mistakes

running the smoke test with no server up — curl: (7) Failed to connect means terminal 1 is not running
calling http://localhost:8080/students — this office lives under /v1/; the 404 body tells you so
thinking the API is the database — it is the counter in front of it

🏭 Why this matters in production: every system you will meet — payments, maps, your company's own services — is a set of counters. Teams that treat the counter as a product (documented, versioned, guarded, observed) ship faster than teams whose apps rummage in each other's drawers.

⏭️ Next

What exactly is written on a slip and a stamp? HTTP anatomy — method, path, headers, body, status.

git checkout lesson-02-http-anatomy

← Course homeall lessons Next →http anatomy

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