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

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

🔀 धडा 11 — REST च्या पलीकडे: जेव्हा काउंटर तुम्हाला परत कॉल करतो

📍 तुम्ही इथे आहात: 12 पैकी धडा 11 · मागील: lesson-10-rate-limits-caching · पुढील: lesson-12-testing-docs-gateway

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

धडे 01–10, आणि त्यासोबत काउंटरचे इतर आकार — GraphQL, gRPC, webhooks, events — आणि त्यातला एक निवडण्याचा नियम. खऱ्या files:

api/webhook_receiver.py — जिथे काउंटर तुम्हाला परत कॉल करतो, जेमतेम डझनभर ओळी
api/api_types.py — तेच पाच विद्यार्थी REST, JSON-RPC, GraphQL, long polling, SSE आणि एका खऱ्या WebSocket मधून दिले जातात
api/types_client.py — सहाही वापरून पाहणारा आणि प्रत्येक byte छापणारा एकच client

🔀 संपूर्ण नकाशा: हा धडा नेहमी भेटणारे चार आकार शिकवतो. इतर प्रत्येक प्रकार — SOAP, tRPC, OData, WebRTC, queues, event streams, batch files, आणि network ला कधीच न शिवणारे APIs (libraries, system calls, database drivers) — म्हणजे धडा 15 — प्रत्येक API प्रकार: एक मुख्य तक्ता, चार कुटुंबे आणि एक निर्णय-मार्गदर्शन.

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

REST हा काउंटरचा एक प्रकार आहे: नावे दिलेले drawers, ठरलेल्या slips. आणखी तीन प्रकार आहेत, आणि प्रत्येकामागे खरे कारण आहे:

GraphQL 🧩 — एक खिडकी, जिथे तुम्हाला नेमके कोणते डबे हवेत ते लिहिता ("विद्यार्थी 2: फक्त नाव आणि grade, आणि त्याच्या वर्गाची शिक्षिका"). एका screen ला पाच drawers मधले तुकडे हवे असतील तेव्हा उत्तम; पण office ला प्रत्येक slip वर जास्त विचार करावा लागतो.
gRPC ⚡ — दोन offices मधली जलद अंतर्गत खिडकी: typed forms (.proto), binary, streaming. इमारतीच्या आत machines चे machines शी बोलणे, सार्वजनिक काउंटर नव्हे.
Webhooks 📣 — तुम्ही काउंटरवर तुमचा फोन नंबर ठेवता ("विद्यार्थी दाखल झाला की मला कॉल करा"). ते घडले की office तुम्हाला कॉल करते (तुमच्या URL वर POST), तुम्ही दर पाच सेकंदाला विचारत बसण्याऐवजी.
Events / queues 📬 — काही घडले की दर वेळी office एका कप्प्यात चिठ्ठी टाकते; कोणीही तो कप्पा नंतर, क्रमाने वाचू शकतो. मोठ्या प्रमाणावर "घडले की मला सांगा" साठी, replay सह.

निवड म्हणजे फॅशन नव्हे: आकार caller नुसार ठरतो.

🗺️ आकृती

flowchart LR
    rest["🗄️ REST<br/>nouns + verbs, cacheable — public, simple"]
    gql["🧩 GraphQL<br/>ask for exactly these fields — one UI, many shapes"]
    grpc["⚡ gRPC<br/>typed, binary, streaming — service ↔ service"]
    hook["📣 webhooks<br/>the counter calls you back on events"]
    ev["📬 events / queues<br/>'tell me when', replayable"]
    caller["🧭 the shape follows the caller"] --> rest & gql & grpc & hook & ev

❓ काय

GraphQL: एक endpoint (POST /graphql), एक query भाषा, एक typed schema, नेमके-तेवढेच-fields असलेली उत्तरे. किंमत: caching अवघड होते (प्रत्येक resource ला वेगळी URL नाही), आणि बेबंद queries ना depth/cost मर्यादा लागतात.
gRPC: HTTP/2 + Protocol Buffers; प्रत्येक भाषेत तयार होणारे clients; दोन्ही दिशांनी streaming. किंमत: browser मध्ये थेट चालत नाही (proxy लागतो), curl ने चालवता येत नाही, तारेवर binary.
Webhooks: consumer एक URL नोंदवतो; producer त्यावर events POST करतो. Consumer पोहोचण्याजोगा असला पाहिजे, त्याने signature तपासली पाहिजे, जलद उत्तर (2xx) दिले पाहिजे आणि retries आणि duplicates सहन केले पाहिजेत (handling idempotent करा — पुन्हा धडा 07).
Events: एक log किंवा queue (Kafka, SQS, RabbitMQ); consumers आपापल्या गतीने pull करतात, क्रम आणि replay सह. Server-sent events (SSE) आणि WebSockets browsers कडे stream करतात.
Polling ची जागा हे सगळे घेतात: दर N सेकंदाला "काही नवीन?" — हजारो रिकामी उत्तरे, आणि तरीही उशीर. Long polling हा प्रामाणिक मधला मार्ग: एक request, जी बातमी येईपर्यंत server धरून ठेवतो.
SSE (text/event-stream) हा एकदिशी stream: server एका उघड्या connection वरून id/event/data frames पाठवतो, आणि browsers Last-Event-ID वापरून स्वतःहून पुन्हा जोडतात. WebSocket एका HTTP request चे (101 Switching Protocols) एका socket मध्ये रूपांतर करते, जो दोन्ही बाजू वापरू शकतात — chat, cursors, live dashboards.
याच कुटुंबात आणखी (प्रत्येक API प्रकार धडा 15 पाहा): SOAP/XML-RPC — banking मध्ये भेटणारा नोटरी केलेला लिफाफा; tRPC — एका TypeScript codebase मधले typed calls; OData — query भाषा असलेले REST; WebRTC — media साठी peer to peer; batch file drops (SFTP, CSV) — payroll आणि banking आजही लाखो rows अशाच हलवतात; आणि network नसलेले APIs: libraries/SDKs, system calls, database drivers.

🤔 का

कारण टीम्स फॅशन पाहून आकार निवडतात आणि वर्षानुवर्षे त्याची किंमत मोजतात: दोन endpoints असलेल्या service साठी GraphQL API, browsers ना call करायचा असलेल्या public API साठी gRPC, जिथे webhook फक्त एका नोंदणीच्या अंतरावर होता तिथे polling. चार आकार आणि एक नियम माहीत असला, की निवड बहुतेक वेळा उघड असते.

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

POST /v1/webhooks {"url": …} एक URL नोंदवतो; school_api.py मधला notify() यशस्वी प्रवेशानंतर प्रत्येक नोंदवलेल्या URL वर student.created event POST करतो — आणि अपयश गिळून टाकतो, कारण बंद पडलेल्या webhook मुळे काउंटर कधीच बिघडता कामा नये. api/webhook_receiver.py ही दुसरी बाजू आहे: जे येते ते छापणारा 15 ओळींचा server.

🧪 करून पाहा

# A) six shapes, one dataset — REST · JSON-RPC · GraphQL · long polling · SSE · WebSocket
python3 api/api_types.py &                                           # :8081
python3 api/types_client.py                                          # every byte of all six, printed
# read the differences: whole resource vs chosen fields vs an error inside a 200 vs a held request vs a stream vs a socket

# B) the webhook, from both sides:
python3 api/webhook_receiver.py &                                    # terminal 3: your phone rings here on :9090
B=http://127.0.0.1:8080/v1; K='X-API-Key: hall-pass-123'; J='Content-Type: application/json'
curl -s -X POST $B/webhooks -H "$J" -d '{"url":"http://127.0.0.1:9090/hook"}'
curl -s -X POST $B/students -H "$K" -H "$J" -d '{"name":"Zoya","class":"3B"}' > /dev/null
# terminal 3 prints: 📣 webhook received: {'event': 'student.created', 'student': {...}}
kill %1                                                              # now the receiver is dead —
curl -s -X POST $B/students -H "$K" -H "$J" -d '{"name":"Yash","class":"3A"}' | head -c 80   # still 201: the counter survives

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

types_client.py नावे दिलेले सहा विभाग छापतो आणि ✅ six shapes, one dataset ने संपतो: REST पूर्ण resources परत देते, JSON-RPC error एका 200 च्या आत परत देते, GraphQL फक्त तुम्ही सांगितलेले fields देते, long polling ~0.4 s उशिरा एका event सह उत्तर देते, SSE id:/event:/data: frames छापते (आणि तुम्ही Last-Event-ID: 0 पाठवल्यावर इतिहास replay करते), आणि WebSocket दोन्ही दिशांनी echo करण्याआधी 101 Switching Protocols दाखवते.

Receiver नव्या विद्यार्थ्यासह एक 📣 webhook received ओळ छापतो; तुम्ही तो बंद केल्यावरही पुढचा प्रवेश 201 च देतो आणि server च्या log मध्ये webhook … failed दिसते — अपयशी callback मुळे काउंटर कधीच बिघडत नाही.

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

काउंटर तुम्हाला परत कॉल करू शकतो, आणि webhooks चे दोन नियम तुम्ही दोन्ही बाजूंनी पाहिले: producer कधीच consumer साठी अडकून राहत नाही, आणि consumer ने retries ची अपेक्षा ठेवलीच पाहिजे.

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

signature शिवाय webhooks — कोणीही तुमच्या URL वर खोटे events POST करू शकतो
2xx उत्तर देण्याआधी काम करणारा webhook handler — आधी जलद उत्तर द्या, काम नंतर करा (queue)
exactly-once delivery गृहीत धरणे — event id वरून duplicates काढा
query depth/cost मर्यादा नसलेले GraphQL — एकच query denial of service ठरू शकते
थेट browsers कडे gRPC — शेवटी तुम्हाला REST proxy लिहावाच लागेल

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: payments, CI systems आणि chat platforms सगळे निकाल webhook ने पोहोचवतात; अंतर्गत microservices gRPC बोलतात; screens endpoints पेक्षा मोठे झाले की product UIs GraphQL स्वीकारतात. भागीदार कोणता आकार वापरतो — आणि का — हे ओळखणे हे रोजचे कौशल्य आहे.

⏭️ पुढे

शेवटचा टप्पा: contract tests, कॅटलॉगमधून docs, आणि शाळेचे गेट (API gateway) प्रत्येक काउंटरसमोर.

git checkout lesson-12-testing-docs-gateway

🔀 Lesson 11 — Beyond REST: when the counter calls you back

📍 You are here: Lesson 11 of 12 · Previous: lesson-10-rate-limits-caching · Next: lesson-12-testing-docs-gateway

📦 What's in this branch

Lessons 01–10, plus the other shapes a counter can take — GraphQL, gRPC, webhooks, events — and the rule for picking one. Real files:

api/webhook_receiver.py — where the counter calls you back, barely a dozen lines
api/api_types.py — the same five students served as REST, JSON-RPC, GraphQL, long polling, SSE and a real WebSocket
api/types_client.py — one client that exercises all six and prints every byte

🔀 The full map: this lesson teaches the four shapes you meet most. Every other type — SOAP, tRPC, OData, WebRTC, queues, event streams, batch files, and the APIs that never touch a network (libraries, system calls, database drivers) — is lesson 15 — every API type: one master table, four families, and a decision guide.

🧒 Explain like I'm 5

REST is one kind of counter: named drawers, standard slips. Three other kinds exist, each for a real reason:

GraphQL 🧩 — one window where you write exactly which boxes you want ("student 2: name and grade only, plus their class's teacher"). Great when one screen needs bits of five drawers; the office has to do more thinking per slip.
gRPC ⚡ — a fast internal hatch between two offices: typed forms (.proto), binary, streaming. Machines talking to machines inside the building, not the public counter.
Webhooks 📣 — you leave your phone number at the counter ("call me when a student is enrolled"). When it happens, the office calls you (POST to your URL) instead of you asking every five seconds.
Events / queues 📬 — the office puts a note in a pigeonhole every time something happens; anyone may read the pigeonhole later, in order. For "tell me when" at scale, with replay.

Picking is not fashion: the shape follows the caller.

🗺️ Diagram

flowchart LR
    rest["🗄️ REST<br/>nouns + verbs, cacheable — public, simple"]
    gql["🧩 GraphQL<br/>ask for exactly these fields — one UI, many shapes"]
    grpc["⚡ gRPC<br/>typed, binary, streaming — service ↔ service"]
    hook["📣 webhooks<br/>the counter calls you back on events"]
    ev["📬 events / queues<br/>'tell me when', replayable"]
    caller["🧭 the shape follows the caller"] --> rest & gql & grpc & hook & ev

❓ What

GraphQL: one endpoint (POST /graphql), a query language, a typed schema, exactly-the-fields responses. Costs: caching is harder (no URL per resource), and unbounded queries need depth/cost limits.
gRPC: HTTP/2 + Protocol Buffers; generated clients in every language; bidirectional streaming. Costs: not browser-native (needs a proxy), not curl-able, binary on the wire.
Webhooks: the consumer registers a URL; the producer POSTs events to it. The consumer must be reachable, verify a signature, answer fast (2xx) and tolerate retries and duplicates (make handling idempotent — lesson 07 again).
Events: a log or queue (Kafka, SQS, RabbitMQ); consumers pull at their pace, with ordering and replay. Server-sent events (SSE) and WebSockets stream to browsers.
Polling is what all of these replace: "anything new?" every N seconds — thousands of empty answers, and still late. Long polling is the honest middle: one request the server holds until there is news.
SSE (text/event-stream) is the one-way stream: the server sends id/event/data frames down one open connection, and browsers reconnect by themselves with Last-Event-ID. WebSocket upgrades an HTTP request (101 Switching Protocols) into one socket both sides may use — chat, cursors, live dashboards.
Also in the family (see the every API type lesson 15): SOAP/XML-RPC — the notarised envelope you will meet in banking; tRPC — typed calls inside one TypeScript codebase; OData — REST with a query language; WebRTC — peer to peer for media; batch file drops (SFTP, CSV) — still how payroll and banking move millions of rows; and the non-network APIs: libraries/SDKs, system calls, database drivers.

🤔 Why

Because teams pick shapes by fashion and pay for years: a GraphQL API for a two-endpoint service, gRPC for a public API browsers must call, polling where a webhook was one registration away. Know the four shapes and the one rule, and the choice is usually obvious.

🔧 How (in this repo)

POST /v1/webhooks {"url": …} registers a URL; notify() in school_api.py POSTs a student.created event to every registered URL after a successful enrolment — and swallows failures, because a dead webhook must never break the counter. api/webhook_receiver.py is the other side: a 15-line server that prints what arrives.

🧪 Try it

# A) six shapes, one dataset — REST · JSON-RPC · GraphQL · long polling · SSE · WebSocket
python3 api/api_types.py &                                           # :8081
python3 api/types_client.py                                          # every byte of all six, printed
# read the differences: whole resource vs chosen fields vs an error inside a 200 vs a held request vs a stream vs a socket

# B) the webhook, from both sides:
python3 api/webhook_receiver.py &                                    # terminal 3: your phone rings here on :9090
B=http://127.0.0.1:8080/v1; K='X-API-Key: hall-pass-123'; J='Content-Type: application/json'
curl -s -X POST $B/webhooks -H "$J" -d '{"url":"http://127.0.0.1:9090/hook"}'
curl -s -X POST $B/students -H "$K" -H "$J" -d '{"name":"Zoya","class":"3B"}' > /dev/null
# terminal 3 prints: 📣 webhook received: {'event': 'student.created', 'student': {...}}
kill %1                                                              # now the receiver is dead —
curl -s -X POST $B/students -H "$K" -H "$J" -d '{"name":"Yash","class":"3A"}' | head -c 80   # still 201: the counter survives

✅ Verify — what you should see

types_client.py prints six labelled sections and ends with ✅ six shapes, one dataset: REST returns whole resources, JSON-RPC returns error inside a 200, GraphQL returns only the fields you named, long polling answers ~0.4 s late with one event, SSE prints id:/event:/data: frames (and replays history when you send Last-Event-ID: 0), and the WebSocket shows 101 Switching Protocols before echoing both ways.

The receiver prints one 📣 webhook received line with the new student; after you kill it, the next enrolment still returns 201 and the server's log shows webhook … failed — a failing callback never breaks the counter.

🏁 What you just proved

The counter can call you back, and you saw the two rules of webhooks from both sides: the producer never blocks on the consumer, and the consumer must expect retries.

⚠️ Common mistakes

webhooks without a signature — anyone can POST fake events to your URL
a webhook handler that does the work before answering 2xx — answer fast, do the work after (a queue)
assuming exactly-once delivery — de-duplicate by event id
GraphQL without query depth/cost limits — one query can be a denial of service
gRPC straight to browsers — you will end up writing the REST proxy anyway

🏭 Why this matters in production: payments, CI systems and chat platforms all deliver results by webhook; internal microservices talk gRPC; product UIs adopt GraphQL when screens outgrow endpoints. Recognising which shape a partner uses — and why — is a daily skill.

⏭️ Next

The last mile: contract tests, docs from the catalogue, and the school gate (API gateway) in front of every counter.

git checkout lesson-12-testing-docs-gateway

← Previousrate limits caching Next →testing docs gateway

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