15 · 🔀 प्रत्येक API प्रकार — एक शाळा, अनेक काउंटर

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

धडे 01–15. तेच पाच विद्यार्थी सहा API आकारांतून दिले जातात:

api/api_types.py — REST · JSON-RPC · GraphQL-lite · long polling · Server-Sent Events · एक खरा WebSocket (RFC 6455 handshake आणि frames)
api/types_client.py — सहाही वापरून पाहणारा आणि प्रत्येक byte छापणारा एकच client
api/api-types-output.txt — निरोगी run काय छापतो
🗺️ संपूर्ण नकाशा: https://school-edh.pages.dev/api/lesson-diagrams.html#l15 — एका ओळीत एक असे काढलेले वीस प्रकार, चार कुटुंबे, मुख्य तक्ता, वापरकर्त्यानुसार, शैलीनुसार, निर्णय-मार्गदर्शन, चुका

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

शाळेत एकापेक्षा जास्त प्रकारचे काउंटर आहेत. फ्रंट ऑफिसमध्ये तुम्ही विचारता आणि उत्तर मिळवता (REST, RPC, GraphQL, gRPC, SOAP, tRPC, OData). फोनवर तुम्ही line वर थांबता आणि office बोलत राहते (long polling, Server-Sent Events, WebSocket, WebRTC). कप्प्यांजवळ तुम्ही निरोप ठेवता आणि कोणीच थांबत नाही (webhooks, queues, event streams, MQTT, batch files ची रात्रीची गाडी). आणि काही काउंटर network वर मुळीच नसतात — तुमच्याच दप्तरातले साधन (library), इमारतीचा व्यवस्थापक (system calls), नोंदींच्या खोलीपर्यंतची तार (database driver), भिंतीतला socket (device APIs). तीन प्रश्न कोणत्याही API ला जागा देतात: सुरुवात कोण करतो, line किती वेळ उघडी राहते, आणि वाट कोण पाहतो.

🗺️ आकृती

flowchart LR
  A["1️⃣ ask & answer<br/>REST · JSON-RPC · SOAP<br/>GraphQL · gRPC · tRPC · OData"]
  B["2️⃣ stay on the line<br/>long polling · SSE<br/>WebSocket · WebRTC"]
  C["3️⃣ leave a message<br/>webhooks · queues · MQTT<br/>event streams · batch files"]
  D["4️⃣ no network at all<br/>library · system calls<br/>DB drivers · device APIs"]
  Q{"WHO starts? · HOW LONG is the line open? · WHO waits?"} --> A & B & C & D

❓ काय

संपूर्ण नकाशावरच्या मुख्य तक्त्यात सगळे वीस आहेत. थोडक्यात:

REST कपाटांतली नामे · RPC नावाने बोलावलेले क्रियापद · GraphQL उत्तराचा आकार तुम्ही लिहिता · gRPC typed अंतर्गत खिडकी · SOAP नोटरी केलेला लिफाफा
Long polling कारकून तुमचा प्रश्न धरून ठेवतो · SSE ध्वनिक्षेपक · WebSocket उघडी फोन line · WebRTC टेबल ते टेबल
Webhook तुम्ही तुमचा नंबर ठेवता · Queue एकच वाचक · Event stream सगळे पुन्हा वाचतात ती नोंदवही · MQTT छोट्या devices साठी सार्वजनिक उद्घोषणा यंत्रणा · Batch रात्रीची गाडी
Library, system call, database driver, device — network ला कधीच न शिवणारे contracts, आणि त्यांनाही हेच धडे लागू होतात

🤔 का

कोणीही benchmark पाहून प्रकार निवडत नाही; संवाद कोण सुरू करतो, उत्तर किती ताजे हवे, आणि एखादा माणूस वाट पाहत आहे का, यावरून निवडतात. अनोळखी तंत्रज्ञान चार कुटुंबांपैकी एकात बसवले की त्याच्या docs ची एक ओळ वाचण्याआधीच ते काय करू शकते आणि काय नाही याचा बहुतेक अंदाज येतो.

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

api_types.py हा एकाच data वर सहा दारे असलेला एक ThreadingHTTPServer आहे: एक REST route, एक JSON-RPC method table, फक्त मागितलेले fields परत देणारा GraphQL-lite resolver, Condition वर वाट पाहणारा long-poll, id: frames आणि Last-Event-ID असलेला SSE stream, आणि SHA-1 handshake करून हाताने frames mask करणारा WebSocket — सुमारे 160 ओळी, त्यात कोणतीही जादू नाही.

🧪 करून पाहा

python3 api/api_types.py &
python3 api/types_client.py
# then by hand:
curl -s -X POST http://127.0.0.1:8081/graphql -H 'Content-Type: application/json' -d '{"query":"{ students { name } }"}'
curl -N http://127.0.0.1:8081/events &   # a stream: enrol a student through JSON-RPC and watch it arrive

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

नावे दिलेले सहा विभाग: REST पूर्ण resources परत देते; JSON-RPC एका 200 च्या आत error परत देते; GraphQL नेमके तुम्ही सांगितलेले fields देते; long polling सुमारे 0.4 s उशिरा एका event सह उत्तर देते; SSE id: / event: / data: frames छापते आणि Last-Event-ID: 0 साठी इतिहास replay करते; WebSocket 101 Switching Protocols दाखवते आणि मग दोन्ही दिशांनी echo करते. पूर्ण मजकूर: api/api-types-output.txt.

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

API प्रकारांमधला फरक म्हणजे सुरुवात कोण करतो, किती वेळा, आणि किती परत येते — data नव्हे. तुम्ही सहा तारांवरून तेच पाच विद्यार्थी जाताना पाहिले.

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

लोकप्रियतेवरून निवडणे; क्वचित घडणाऱ्या events साठी दर काही सेकंदाला polling.
साध्या request/response साठी WebSocket; थेट browsers कडे gRPC.
Caller ला उत्तर आत्ताच हवे असताना queue; signatures किंवा idempotency नसलेले webhooks.
Library API ला "खरा API नाही" समजणे — versioning आणि deprecation त्यालाही लागू होतात.

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: आकार एकमेकांत जुळतात. Job queue मध्ये टाकणारा, SSE वरून progress stream करणारा आणि webhook ने संपणारा REST काउंटर म्हणजे प्रत्येक कुटुंब ज्यात चांगले आहे त्यासाठी वापरणारी एक architecture — आणि कोणत्याही थरावरची चुकीची निवड एकतर प्रत्येक client मागे एक रिकामा पडलेला socket किंवा कोणीच न रिकामी करणारी queue म्हणून दिसते.

⏭️ पुढे

धडा 16 — API test चा प्रत्येक प्रकार: प्रकार कोणताही असो, काउंटरची test त्याच नऊ पद्धतींनी होते.

15 · 🔀 Every API type — one school, many counters

📦 What's in this branch

Lessons 01–15. The same five students served through six API shapes:

api/api_types.py — REST · JSON-RPC · GraphQL-lite · long polling · Server-Sent Events · a real WebSocket (RFC 6455 handshake and frames)
api/types_client.py — one client that exercises all six and prints every byte
api/api-types-output.txt — what a healthy run prints
🗺️ The full map: https://school-edh.pages.dev/api/lesson-diagrams.html#l15 — twenty types drawn one per row, the four families, the master table, by audience, by style, a decision guide, the mistakes

🧒 Explain like I'm 5

The school has more than one kind of counter. At the front office you ask and get an answer (REST, RPC, GraphQL, gRPC, SOAP, tRPC, OData). On the phone you stay on the line and the office keeps talking (long polling, Server-Sent Events, WebSocket, WebRTC). At the pigeonholes you leave a message and nobody waits (webhooks, queues, event streams, MQTT, the nightly van of batch files). And some counters are not on the network at all — the tool in your own bag (a library), the building manager (system calls), the wire to the record room (a database driver), the socket in the wall (device APIs). Three questions place any API: who starts, how long does the line stay open, and who waits.

🗺️ Diagram

flowchart LR
  A["1️⃣ ask & answer<br/>REST · JSON-RPC · SOAP<br/>GraphQL · gRPC · tRPC · OData"]
  B["2️⃣ stay on the line<br/>long polling · SSE<br/>WebSocket · WebRTC"]
  C["3️⃣ leave a message<br/>webhooks · queues · MQTT<br/>event streams · batch files"]
  D["4️⃣ no network at all<br/>library · system calls<br/>DB drivers · device APIs"]
  Q{"WHO starts? · HOW LONG is the line open? · WHO waits?"} --> A & B & C & D

❓ What

The master table on the full map has all twenty. The short version:

REST nouns in cabinets · RPC a verb by name · GraphQL you write the shape of the answer · gRPC the typed internal hatch · SOAP the notarised envelope
Long polling the clerk holds your question · SSE the loudspeaker · WebSocket the open phone line · WebRTC desk to desk
Webhook you leave your number · Queue one reader · Event stream the logbook everyone replays · MQTT the PA system for tiny devices · Batch the nightly van
Library, system call, database driver, device — contracts that never touch a network, and the same lessons apply

🤔 Why

Nobody picks a type by benchmark; they pick by who starts the conversation, how fresh the answer must be, and whether a human is waiting. Placing an unfamiliar technology on the four families tells you most of what it can and cannot do before you read a line of its docs.

🔧 How (in this repo)

api_types.py is one ThreadingHTTPServer with six doors on the same data: a REST route, a JSON-RPC method table, a GraphQL-lite resolver that returns only the fields asked for, a long-poll that waits on a Condition, an SSE stream with id: frames and Last-Event-ID, and a WebSocket that does the SHA-1 handshake and masks frames by hand — about 160 lines, none of them magic.

🧪 Try it

python3 api/api_types.py &
python3 api/types_client.py
# then by hand:
curl -s -X POST http://127.0.0.1:8081/graphql -H 'Content-Type: application/json' -d '{"query":"{ students { name } }"}'
curl -N http://127.0.0.1:8081/events &   # a stream: enrol a student through JSON-RPC and watch it arrive

✅ Verify — what you should see

Six labelled sections: REST hands back whole resources; JSON-RPC returns an error inside a 200; GraphQL returns exactly the fields you named; long polling answers about 0.4 s late with one event; SSE prints id: / event: / data: frames and replays history for Last-Event-ID: 0; the WebSocket shows 101 Switching Protocols then echoes both ways. Full text: api/api-types-output.txt.

🏁 What you just proved

The difference between API types is who starts, how often, and how much comes back — not the data. You saw six wires carry the same five students.

⚠️ Common mistakes

Choosing by popularity; polling every few seconds for rare events.
A WebSocket for plain request/response; gRPC straight to browsers.
A queue when the caller needs the answer now; webhooks without signatures or idempotency.
Treating a library API as "not a real API" — versioning and deprecation apply to it too.

🏭 Why this matters in production: the shapes compose. A REST counter that enqueues a job, streams progress over SSE and finishes with a webhook is one architecture using each family for what it is good at — and a bad choice at any layer shows up as either an idle socket per client or a queue nobody drains.

⏭️ Next

Lesson 16 — every kind of API test: whatever its type, a counter is tested the same nine ways.

← Previousauth methods Next →testing types

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