🏢 शाळेच्या पद्धतीने API शिका

1 🏢 API का

फ्रंट ऑफिस — कोणीही दप्तरखान्यात भटकत नाही; तुम्ही काउंटरवर, प्रमाणित चिठ्ठीवर विचारता.

संपूर्ण धडा 01 वाचा →

2 📨 HTTP ची रचना

विनंतीची चिठ्ठी आणि कारकुनाचा शिक्का — method, path, headers, body, status code.

संपूर्ण धडा 02 वाचा →

3 🗄️ REST resources

फाइलिंग कपाटांतली नामे — संग्रह, ids, आणि पुन्हा-पुन्हा करायला सुरक्षित क्रियापदे.

संपूर्ण धडा 03 वाचा →

4 📋 JSON & schemas

प्रमाणित फॉर्म — प्रत्येक चिठ्ठीसाठी एकच आकार, OpenAPI कॅटलॉगमध्ये छापलेला.

संपूर्ण धडा 04 वाचा →

5 🔬 API बांधा

Python च्या ~340 प्रामाणिक ओळींतले काउंटर — routes, validation, storage, plumbing.

संपूर्ण धडा 05 वाचा →

6 🪪 Auth

काउंटरवरचे हॉल पास — API keys, bearer tokens, OAuth, आणि कोण लिहू शकतो.

संपूर्ण धडा 06 वाचा →

7 ⚠️ चुका & idempotency

कारणासह नम्र नकार — आणि पावती क्रमांक, म्हणजे पुन्हा-प्रयत्न कधीच दुहेरी नोंद करत नाहीत.

संपूर्ण धडा 07 वाचा →

8 📚 Pagination & filtering

'पुढचे 20, कृपया' — cursors, filters आणि sorting, कोणालाही न गमावता.

संपूर्ण धडा 08 वाचा →

9 🔢 Versioning

जुने फॉर्म न फेकता नवे फॉर्म — additive बदल, deprecation, sunset.

संपूर्ण धडा 09 वाचा →

10 ⏱️ Rate limits & caching

काउंटरवरची रांग — 429, Retry-After, ETags, timeouts आणि backoff.

संपूर्ण धडा 10 वाचा →

11 🔀 REST च्या पलीकडे

GraphQL, gRPC, webhooks आणि events — जेव्हा काउंटर तुम्हाला परत कॉल करतो.

संपूर्ण धडा 11 वाचा →

12 🚪 चाचण्या, docs & gateway

Contract tests, छापलेला कॅटलॉग, आणि प्रत्येक काउंटरसमोरचे शाळेचे गेट.

संपूर्ण धडा 12 वाचा →

13 🔧 प्रत्येक REST method

सात शिक्के — GET, HEAD, OPTIONS, POST, PUT, PATCH, DELETE — आणि त्यांना वेगळे करणारे तीन शब्द: safe, idempotent, cacheable.

📋 तक्ता — सात methods, एक पडदा

आधी Safe आणि Idempotent स्तंभ वाचा: काय पुन्हा पाठवता येते, cache होते, आधीच आणले जाते आणि preflight होते हे ते ठरवतात. चित्राकडे उडी मारायला method वर क्लिक करा.

🧠 तीन शब्द

🖼️ प्रत्येक method, काउंटरवर काढलेली

तुटक बाण म्हणजे एकेक संदेश. प्रत्येक चित्र काउंटर खरोखर स्वीकारते ती विनंती आणि api/methods_demo.sh ला मिळणारे नेमके उत्तर दाखवते.

🔢 प्रत्येक method कोणते status codes देते

कारकुनाचे शिक्के, method नुसार. संपूर्ण शिक्क्यांचा कॅटलॉग धडा 02; प्रत्येक 4xx साठी एकच error shape धडा 07.

🧭 PUT विरुद्ध PATCH विरुद्ध POST — छोटे निर्णय-मार्गदर्शन

🔬 चालवा — खऱ्या काउंटरवर प्रत्येक method

api/methods_demo.sh सातही methods api/school_api.py कडे पाठवते आणि प्रत्येक नियम सिद्ध करणारे headers छापते: GET आणि HEAD वरचा ETag, OPTIONS वरची Allow यादी, दोन POST मधून दोन Locations, दोन PUT मधून एकच विद्यार्थी, अर्धवट PUT ला 400, एकत्र केलेला PATCH, आणि DELETE ला दोनदा 204.

python3 api/school_api.py        # terminal 1
bash api/methods_demo.sh         # terminal 2

तुम्हाला काय दिसायला हवे:

── GET — read it · safe · idempotent · cacheable
   HTTP/1.0 200 OK
   ETag: "72bc985b4c68bcd2"
   Cache-Control: private, max-age=30
   {"id": 2, "name": "Katrina", "class": "3A", "grade": "A+"}

── HEAD — GET's headers without the body: same ETag and Content-Length, zero bytes of body
   HTTP/1.0 200 OK
   Content-Length: 58
   ETag: "72bc985b4c68bcd2"

── OPTIONS — what may I do here? (also the browser's CORS preflight)
   HTTP/1.0 204 No Content
   Allow: GET, HEAD, PUT, PATCH, DELETE, OPTIONS
   Access-Control-Allow-Methods: GET, HEAD, PUT, PATCH, DELETE, OPTIONS

── POST — create a NEW one · NOT idempotent: the same form twice = two students (unless Idempotency-Key, lesson 07)
   HTTP/1.0 201 Created
   Location: /v1/students/6
   HTTP/1.0 201 Created
   Location: /v1/students/7

── PUT — REPLACE the whole student · idempotent: twice = the same student
{"id": 2, "name": "Katrina", "class": "3B", "grade": "A+"}
{"id": 2, "name": "Katrina", "class": "3B", "grade": "A+"}

── PUT with only one field — a replace means ALL the fields, so this is a 400 with problems
{"error": {"code": "validation_failed", "message": "The form has problems.", "problems": [{"field": "name", "problem": "required, non-empty string"}, {"field": "class", "problem": "must be one of ['3A', '3B']"}]}}

── PATCH — change PART of the student: send only what changes
{"id": 2, "name": "Katrina", "class": "3B", "grade": "A"}

── PATCH with a field that does not exist — 400, never a silent ignore
{"error": {"code": "validation_failed", "message": "Unknown fields.", "problems": [{"field": "nickname", "problem": "not a student field"}]}}

── DELETE — remove it · idempotent: the second DELETE is still 204, because the state is the same (gone)
   first:  204   second: 204   GET afterwards: 404

── the unsafe methods need the hall pass (lesson 06); the safe ones never do
   DELETE without a key: 401   GET without a key: 200

── and one that is NOT a method: /students/5/delete as a GET is a smell — GET must never change anything
   404  ← 404: no such noun, and no verb hidden in the URL

✅ seven methods, one counter — safe · idempotent · body · cacheable decide which one you reach for

⚠️ तीन शब्द मोडणाऱ्या चुका

संपूर्ण धडा 13 वाचा →

14 🪪 प्रत्येक authentication पद्धत

हॉल पास दाखवण्याचा प्रत्येक मार्ग — Basic, API keys, Bearer tokens, JWT, cookies, OAuth 2.0 आणि त्याचे grant types, OpenID Connect, HMAC signing, mutual TLS.

🚦 401 विरुद्ध 403 — दोन नकार

📋 मुख्य तक्ता — नऊ पद्धती एका पडद्यावर

आधी Server स्थिती ठेवतो? वाचा: तुम्ही तत्काळ रद्द करू शकता (stateful) की lookup शिवाय वाढू शकता (stateless) हे ते ठरवते. चित्राकडे उडी मारायला नावावर क्लिक करा.

🖼️ प्रत्येक पद्धत, चित्रात

तुटक बाण म्हणजे एकेक संदेश, अखंड बाण म्हणजे handshake. प्रत्येक चित्र ती पद्धत तारेवर जो header ठेवते तो आणि काउंटरचे उत्तर नेमके दाखवते.

🎫 OAuth 2.0 grant types — कोणत्या कॉल करणाऱ्यासाठी कोणते दार

"OAuth" म्हणजे एकच प्रवाह नव्हे. Client token endpoint ला जो grant_type पाठवतो तो सांगतो कोण विचारतोय आणि ते कसे सिद्ध करतात. आज दोन grants जवळजवळ सगळे भागवतात; जुन्या कोडमध्ये भेटणारे दोन गेलेले आहेत.

🎚️ कोणतीही पद्धत बसवणारे पाच प्रश्न

🧭 कोणता? — छोटे निर्णय-मार्गदर्शन

🔬 त्यांपैकी सात चालवा — त्याच grades, सात हॉल पास

api/auth_demo.py एका resource चे सात प्रकारे रक्षण करते — Basic, API key, opaque Bearer token, JWT (HS256, standard library ने स्वाक्षरी आणि तपासणी), HMAC request signing, session cookie, आणि OAuth 2.0 token endpoint (client_credentials आणि refresh_token, password grant नाकारलेला) — प्रत्येक 401 वर योग्य WWW-Authenticate आणि पुसायचा प्रयत्न करणाऱ्या विद्यार्थ्याला खरा 403. api/auth_client.py तारेवरचा प्रत्येक header, संपलेला token, बनावट JWT, फेरफार केलेली signature, पुन्हा वाजवलेली विनंती, आणि insufficient_scope ने DELETE नाकारलेला scope असलेला token दाखवते.

python3 api/auth_demo.py         # terminal 1
python3 api/auth_client.py       # terminal 2

तुम्हाला काय दिसायला हवे (token ची मूल्ये प्रत्येक वेळी वेगळी):

── 1 Basic — the pass you re-show at every door (user:password, base64, on EVERY request)
   no header                                      → 401  send Authorization: Basic base64(user:password)   WWW-Authenticate: Basic realm="school"
   Authorization: Basic dGVhY2hlcj…               → 200  as teacher (teacher) via basic · 2 grades
   wrong password                                 → 401  wrong user or password   WWW-Authenticate: Basic realm="school"
   base64 is NOT encryption — Basic is only ever acceptable over HTTPS

── 2 API key — a program's pass; no person behind it (the counter's X-API-Key, lesson 06)
   no key                                         → 401  no X-API-Key header   WWW-Authenticate: ApiKey realm="school", header="X-API-Key"
   X-API-Key: hall-pass-123                       → 200  as counter-bot (teacher) via apikey · 2 grades
   X-API-Key: made-up                             → 401  unknown key — we cannot tell who you are   WWW-Authenticate: ApiKey realm="school", header="X-API-Key"
   an unknown key = we cannot tell who you are = 401 (strict); the lesson-06 counter says 403 — both are seen in the wild

── 3 Bearer token (opaque) — log in once, get a wristband, show the wristband
   POST /login teacher/chalk                      → 200  token W-TTEyrfwc… expires_in 3600
   no token                                       → 401  send Authorization: Bearer <token>   WWW-Authenticate: Bearer realm="school"
   Authorization: Bearer W-TTEyrfwc…              → 200  as teacher (teacher) via token · 2 grades
   a token issued with ttl=1, 1.2 s later         → 401  token expired   WWW-Authenticate: Bearer realm="school", error="invalid_token", error_description="expired"
   DELETE as student (valid token)                → 403  student is a student: may read grades, not delete them
   401 = who are you? · 403 = I know exactly who you are, and no · the server LOOKS UP each opaque token

── 4 JWT — a SIGNED wristband: the server verifies, it does not look anything up
   header  {'alg': 'HS256', 'typ': 'JWT'}
   payload {'sub': 'teacher', 'role': 'teacher', 'iat': 1790052651, 'exp': 1790056251}   ← readable by anyone; never put secrets in it
   Authorization: Bearer eyJhbGciOiAiSF…          → 200  as teacher (teacher) via jwt · 2 grades
   payload edited to role=headmaster, same signature → 401  JWT bad signature   WWW-Authenticate: Bearer realm="school", error="invalid_token", error_description="bad signature"
   the signature pins the payload; expiry is inside it (exp) — and a stolen JWT is valid until then, so keep them short

── 5 HMAC request signing — you sign the request itself (webhooks, AWS SigV4 style)
   unsigned                                       → 401  sign the request: X-Key-Id, X-Timestamp, X-Signature   WWW-Authenticate: HMAC-SHA256 realm="school", headers="X-Key-Id X-Timestamp X-Signature"
   X-Key-Id key-1 · X-Timestamp 1790052651 · X-Signature 2370b654… → 200  as key key-1 (teacher) via hmac · 2 grades
   same signature, path changed by an attacker    → 401  signature does not match — the request was altered or the secret is wrong   WWW-Authenticate: HMAC-SHA256 realm="school", headers="X-Key-Id X-Timestamp X-Signature"
   valid signature, 15-minute-old timestamp (replay) → 401  timestamp outside the 5-minute replay window   WWW-Authenticate: HMAC-SHA256 realm="school", headers="X-Key-Id X-Timestamp X-Signature"
   the secret never travels; the signature covers method + path + time + body, so nothing can be altered or replayed

── 6 Session cookie — the browser's way: log in, the server sets an HttpOnly cookie, the browser sends it back
   no cookie                                      → 401  no valid session cookie — POST /login first   WWW-Authenticate: Cookie realm="school"
   POST /login                                    → 200  Set-Cookie: sid=Zha4S2aRtC…; HttpOnly; SameSite=Lax
   GET with the cookie jar                        → 200  as teacher (teacher) via session · 2 grades
   HttpOnly = JavaScript cannot read it (XSS cannot steal it) · SameSite = other sites cannot ride it (CSRF)

── 7 OAuth 2.0 client_credentials — a PROGRAM's own door: id + secret → access token, at the token endpoint
   POST /token grant_type=client_credentials (form) → 200  {access_token: _qxFCGv9…, token_type: Bearer, expires_in: 900, scope: grades:read}   Cache-Control: no-store
   GET /oauth/grades · Bearer _qxFCGv9…           → 200  as report-bot (client:grades:read) via oauth · 2 grades
   DELETE with scope=grades:read                  → 403  insufficient_scope   WWW-Authenticate: Bearer realm="school", error="insufficient_scope", scope="grades:write"
   wrong client_secret                            → 401  invalid_client   WWW-Authenticate: Basic realm="token endpoint"
   grant_type=password                            → 400  unsupported_grant_type: 'password' is not offered: people use authorization_code + PKCE, programs use client_credentials
   grant_type=refresh_token                       → 200  new access_token Ka1rN5IR… (the old refresh token is now used up)
   the shape every OAuth server speaks: a FORM to /token, a JSON {access_token, token_type, expires_in, scope} back, errors as {error} — and scope, not identity, decides the 403

✅ seven hall passes, one set of grades — who is asking, how do we know, and for how long

⚠️ हॉल पास वाटून टाकणाऱ्या चुका

संपूर्ण धडा 14 वाचा →

15 🔀 प्रत्येक API प्रकार

एक शाळा, अनेक काउंटर — REST, RPC, GraphQL, gRPC, streams, sockets, webhooks, queues, MQTT, batch फाइल्स, आणि network ला कधीच स्पर्श न करणारी API.

📋 मुख्य तक्ता — प्रत्येक प्रकार एका पडद्यावर

आधी उजवीकडचे दोन स्तंभ वाचा: कशात उत्तम आणि कधी नाही. कोणत्याही benchmark पेक्षा ही जोडी जास्त रचना ठरवते.

🔧 REST ला स्वतःच्या सात methods आहेत — पहा धडा 13, प्रत्येक REST method — आणि प्रकार कोणताही असो, कॉल करणाऱ्याला हॉल पास दाखवावा लागतो — पहा धडा 14, प्रत्येक authentication पद्धत.

🖼️ प्रत्येक प्रकार, चित्रात — कोण कोणाशी बोलतो

प्रत्येक प्रकारासाठी एक ओळ, तक्त्याच्याच क्रमाने: डावे टोक विचारते, उजवे टोक उत्तर देते, तुटक बाण म्हणजे एकेक संदेश, अखंड बाण म्हणजे उघडी लाइन. इथे उडी मारायला तक्त्यातल्या नावावर क्लिक करा.

🌍 वर्गीकरणाचा दुसरा मार्ग: कोणाला कॉल करायची परवानगी आहे

प्रकार "कोणता आकार?" याचे उत्तर देतो. श्रोते "नियम काय?" याचे — आणि आकारापेक्षा श्रोतेच तुमचे जास्त काम ठरवतात.

🎚️ कोणत्याही API चे वर्णन करणारे पाच अक्ष

कोणी तुम्ही न भेटलेल्या तंत्रज्ञानाचे नाव घेतले, तर ते या पाच अक्षांवर ठेवा आणि ते काय करू शकते व काय नाही हे बहुतांश कळेल.

🧭 कोणता? — छोटे निर्णय-मार्गदर्शन

🔬 त्यांपैकी सहा चालवा — तेच पाच विद्यार्थी, सहा आकार

api/api_types.py हा एकच शून्य-dependency server आहे जो त्याच data बद्दल REST, JSON-RPC, GraphQL, long polling, SSE आणि खऱ्या WebSocket (handshake आणि frames सह, ~160 ओळी) म्हणून उत्तर देतो. api/types_client.py सहाही वापरून पाहतो आणि प्रत्येक byte छापतो.

python3 api/api_types.py        # terminal 1
python3 api/types_client.py     # terminal 2

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

── 1 REST — GET /v1/students?class=3A
   → {"items": [{"id": 1, "name": "Aishwarya", "class": "3A", "grade": "A"}, {"id": 2, "name": "Katrina", "class": "3A", "gra
   the shape: you asked for a RESOURCE; you got all of its fields, whether you wanted them or not

── 2 JSON-RPC — POST /jsonrpc  {method: 'students.list'}
   → {"jsonrpc": "2.0", "id": 1, "result": [{"id": 4, "name": "Meera", "class": "3B", "grade": "A"}, {"id": 5, "name": "Rohan
   unknown method → {"code": -32601, "message": "Method not found: students.teleport"}  (an ERROR in a 200 — the RPC way)

── 3 GraphQL — POST /graphql  { students { name grade } }
   → {"data": {"students": [{"name": "Aishwarya", "grade": "A"}, {"name": "Katrina", "grade": "A+"}, {"name": "Dipika", "grad
   ask for less → {"data": {"students": [{"name": "Aishwarya"}, {"name": "Katrina"}, {"name": "Dipika"}, {"n  (no 'class', no 'id' — you chose)

── 4 Long polling — GET /poll?since=0  (the clerk holds it open)
   → answered after 0.4s with 1 event(s): [{"seq": 1, "event": "student.created", "student": {"id": 6, "name": "Zoya", "class": "3B", "grade": "A"}}]
   the shape: ONE request that waits — no news means an empty answer and you ask again

── 5 SSE — GET /events  (a one-way stream; Last-Event-ID resumes it)
    : keep-alive
    : keep-alive
    id: 2
    event: student.created
    data: {"id": 7, "name": "Yash", "class": "3A", "grade": "C"}
   the shape: text/event-stream, id/event/data frames — and browsers resend Last-Event-ID to resume
   resuming from id 0 replays history: id: 1 | event: student.created | data: {"id": 6, "name": "Zoya", "class": "3B", "grade": "A"}

── 6 WebSocket — GET /ws  (Upgrade: websocket)
   handshake: HTTP/1.1 101 Switching Protocols · Sec-WebSocket-Accept: uNRiaq9Sfw1P3AXc4r+qyqV7Ojw=
   → 'hello'   ← {"echo": "hello", "at": 1789998291.82}
   → 'students'   ← {"students": ["Aishwarya", "Katrina", "Dipika", "Meera", "Rohan", "Zoya", "Yash"]}
   the shape: one socket, either side may speak at any time — chat, cursors, live dashboards

✅ six shapes, one dataset — the difference is who starts, how often, and how much comes back

⚠️ चुकीचा प्रकार निवडायला लावणाऱ्या चुका

संपूर्ण धडा 15 वाचा →

16 🧪 API चाचणीचा प्रत्येक प्रकार

काउंटर तपासण्याचे नऊ मार्ग — smoke, functional, integration, regression, load, stress, security, UI, fuzz — आणि ते स्वीकारण्याचा क्रम.

🧪 काउंटर तपासण्याचे नऊ मार्ग — API testing चे प्रकार

प्रकार कोणताही असो, API त्याच नऊ पद्धतींनी तपासले जाते. प्रत्येक ओळ सांगते चाचणी काय विचारते, आणि ती या काउंटरवर कशी चालवाल. धडा 12 पहिल्या तीन बांधतो; बाकीच्या production च्या सवयी.

संपूर्ण धडा 16 वाचा →

17 📈 Performance आणि monitoring

काउंटरवरचे स्टॉपवॉच — प्रत्येक route चे latency percentiles p25, p50, p75, p90, p95, p99, RED metrics, आणि Prometheus, Datadog व CloudWatch API वर कसे लक्ष ठेवतात.

संपूर्ण धडा 17 वाचा →