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

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

🛎️ धडा 01 — API gateway का: शाळेचे front office

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

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

संपूर्ण कोर्समागची एकच कल्पना: प्रत्येक kitchen समोर एकच front office ठेवा. ते प्रत्येक visitor ला तपासते, मोजते, लक्षात ठेवते आणि पुढे पाठवते, त्यामुळे प्रत्येक kitchen ला फक्त स्वयंपाक करायचा असतो. AWS मध्ये ते office म्हणजे Amazon API Gateway. पूर्ण कोर्सभर तुम्ही वापराल त्या खऱ्या files:

apigw/gateway.py — front office: शुद्ध Python मधले API Gateway REST API चे शिकवण्यासाठीचे model (routes, {proxy+}, JWT आणि Lambda authorizers, API keys आणि usage plans, token bucket, stage cache, CORS, access logs, 29 s timeout आणि 10 MB मर्यादा)
apigw/demo.py — प्रत्येक धडा एक छोटा program म्हणून (python3 apigw/demo.py <section>), आणि office localhost:8080 वर उघडण्यासाठी serve
apigw/test_apigw.py — office च्या नियमांवर 12 checks
demo-output.txt — निरोगी run काय print करतो ते

🎒 सुरू करण्याआधी: तुम्हाला फक्त Python 3 लागते, दुसरे काहीही नाही — AWS account नाही, pip install नाही. gateway.py हे शिकवण्यासाठीचे model आहे: AWS docs सांगतात तो क्रम आणि defaults ते पाळते, पण खऱ्या API Gateway मध्ये खूप जास्त settings आहेत. त्याची JWT check HS256 वापरते म्हणून त्याला crypto library लागत नाही; खरे JWT authorizers RS256 signatures issuer च्या public keys विरुद्ध तपासतात. on a real account अशी खूण असलेल्या commands ना AWS CLI आणि credentials लागतात; बाकी सगळे इथेच चालते.

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

एका मोठ्या शाळेत अनेक kitchens 🍳 असतात — एक विद्यार्थ्यांच्या नोंदी बनवते, एक marks बनवते, एक वेळापत्रके बनवते. दिवसभर visitors येत असतात: पालक, शिक्षिका, apps, इतर शाळा.

Front office नसेल तर प्रत्येक kitchen ला सगळे काही स्वतःच करावे लागते: visitor कोण आहे ते तपासणे, किती आले ते मोजणे, गर्दी थांबवणे, visitor book लिहिणे, आणि स्वयंपाकही. प्रत्येक kitchen हे थोडे वेगळे करते, आणि त्यातले एक नेहमी काहीतरी विसरते.

म्हणून शाळा फाटकावर एकच front office 🛎️ बांधते. तिथे एक clerk बसतो. प्रत्येक visitor आधी त्या desk वर थांबतो. Clerk:

badge तपासतो (तुम्ही कोण?),
visitors मोजतो आणि दारावरच गर्दी थांबवतो,
नेहमीची उत्तरे सूचना फलकावर लक्षात ठेवतो,
प्रत्येक भेट visitor book मध्ये लिहितो,
आणि visitor ला योग्य kitchen कडे पुढे पाठवतो — किंवा "असे kitchen नाही" असे सांगतो.

Kitchens लहान आणि सोपी राहतात. ते front office म्हणजेच API gateway.

🗺️ आकृती

flowchart LR
    v["👪 visitors<br/>apps · browsers · partners"]
    office["🛎️ front office — API Gateway<br/>badge check · count · notice board · visitor book"]
    k1["🍳 kitchen: students<br/>GET /students/{id}"]
    k2["🍳 kitchen: marks<br/>POST /marks"]
    no["🚫 404 Not Found<br/>no such kitchen"]
    log["📒 visitor book<br/>metrics + access log"]
    v -->|"1 every request"| office
    office -->|"2 forward"| k1
    office -->|"2 forward"| k2
    office -.->|"no route"| no
    office -.->|"3 write it down"| log

🗺️ काढलेली आवृत्ती + एक lab: https://school-edh.pages.dev/apigateway/lesson-diagrams.html#l01

❓ काय

API gateway — तुमच्या back ends समोर बसणारी managed service, जी प्रत्येक API ला लागणारे काम हाताळते: routing, authentication, throttling, caching, request validation, CORS, TLS, logging आणि metrics.
Amazon API Gateway — AWS चे gateway. तुम्ही routes (method + path) वर्णन करता, आणि प्रत्येकासाठी एक integration (kitchen: Lambda function, HTTP back end, दुसरी AWS service, किंवा mock).
Back end / integration — उत्तर तयार करणारा code. या कोर्समध्ये तो म्हणजे "kitchen".
Managed — तुम्हाला कोणतेही servers चालवायचे नसतात. तुम्ही प्रत्येक request चे पैसे देता (आणि cache सारख्या जादा गोष्टींचे), आणि AWS तुमच्यासाठी office scale करते.
एक पुढचे दार, अनेक back ends — caller ला एकच पत्ता दिसतो, उदाहरणार्थ https://api.school.example, मागे पाच teams पाच services चालवत असल्या तरीही.

🤔 का

कारण auth, limits, logging आणि TLS हे प्रत्येक service साठी तेच काम आहे, आणि त्यात चूक होणे सोपे आहे. प्रत्येक service ते एकटीच बनवते तेव्हा एक token expiry विसरते, दुसरीला rate limit नसते, तिसरी काहीच log करत नाही. Gateway हे काम एकदाच, एकाच जागी, सगळ्यांसाठी एकाच पद्धतीने करते. मग kitchens मध्ये फक्त business logic राहते — आणि त्यांना हात न लावता तुम्ही दारावरचे नियम बदलू शकता.

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

apigw/demo.py मधले office() शाळेचे gateway (school-api) दोन stages (dev, prod) आणि आठ routes सह बनवते. apigw/gateway.py मधले Gateway.handle() प्रत्येक request ला एकाच रांगेतून नेते: CORS preflight → route match → API key → authorizer → throttle → validation → cache → integration → response mapping → access log. why() एक योग्य request आणि अस्तित्वात नसलेल्या kitchen साठी एक request पाठवते. serve() तेच office फक्त standard library वापरून http://localhost:8080 वर उघडते.

🧪 करून पाहा

python3 apigw/demo.py why
python3 - <<'EOF'
import sys; sys.path.insert(0, "apigw"); from demo import office
gw, clock = office()
for p in ("/students/7", "/students/9", "/teachers"):
    st, headers, out = gw.handle("GET", p)
    print(st, p, out)
print(gw.metrics)
print(gw.logs[-1])
EOF
python3 apigw/test_apigw.py

आता office खरोखर उघडा आणि curl ने दारावर टकटक करा:

python3 apigw/demo.py serve &          # the office opens on localhost:8080
sleep 1                                # give the office a second to open
curl -i localhost:8080/students/7
curl -i localhost:8080/students/7      # the same question again
curl -i localhost:8080/teachers
kill %1                                # close the office

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

why हे GET /students/7 → 200 {'id': '7', 'name': 'Aishwarya', 'class': '8B'} X-Cache: Miss आणि GET /teachers → 404 {'message': 'Not Found'} print करते. तुमचा snippet /students/7 आणि /students/9 साठी 200, 404 /teachers {'message': 'Not Found'}, मग counters {'Count': 3, '4XXError': 1, '5XXError': 0, 'CacheHitCount': 0, 'CacheMissCount': 2} आणि visitor book ची शेवटची ओळ print करतो: {'requestId': 'req-0003', 'stage': 'prod', 'httpMethod': 'GET', 'path': '/teachers', 'status': 404, 'principal': None, 'latencyMs': 4, 'integrationLatencyMs': 0}. Tests 12/12 passed ने संपतात.

चालू office सह: server front office open on http://localhost:8080 (stage prod) — Ctrl+C to close print करतो. पहिला curl HTTP/1.0 200 OK, X-Cache: Miss आणि {"id": "7", "name": "Aishwarya", "class": "8B"} दाखवतो; दुसरा X-Cache: Hit दाखवतो — office ने त्याच्या सूचना फलकावरून उत्तर दिले. /teachers हे HTTP/1.0 404 Not Found आणि {"message": "Not Found"} दाखवते.

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

प्रत्येक visitor एकाच desk वरून जातो. Desk ने प्रत्येक भेटीचे उत्तर दिले, ती मोजली, लक्षात ठेवली आणि लिहून ठेवली — आणि kitchen ला फक्त गरज असेल तेव्हाच विचारले गेले.

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

"gateway जादा आहे" म्हणून प्रत्येक service मध्ये पुन्हा auth, rate limits आणि logging बनवणे
gateway स्वतःहूनच back end सुरक्षित करते असे समजणे — तुम्ही configure केलेले तेवढेच ते तपासते
अनोळखी path साठी खरा REST API 404 म्हणेल अशी अपेक्षा करणे: route नसलेल्या path किंवा method साठी खरे REST APIs 403 {"message":"Missing Authentication Token"} असे उत्तर देतात (HTTP APIs 404 Not Found देतात). धडा स्पष्ट राहावा म्हणून हे model 404/405 म्हणते
gateway.py लाच खरी service समजणे — ते model आहे; AWS console चे Test button आणि aws apigateway test-invoke-method हेच पंच आहेत

🏭 प्रत्यक्ष वापरात

On a real account — तुमचे REST आणि HTTP APIs list करा, आणि आधीपासून असलेल्या Lambda function समोर एकाच command ने HTTP API बनवा ("quick create"):

aws apigateway get-rest-apis --query 'items[].{name:name,id:id}'
aws apigatewayv2 get-apis --query 'Items[].{name:Name,id:ApiId,type:ProtocolType}'
aws apigatewayv2 create-api --name school-api --protocol-type HTTP \
    --target arn:aws:lambda:ap-south-1:111122223333:function:students

🏭 Production मध्ये हे का महत्त्वाचे: बहुतेक AWS serverless systems Lambda समोर API Gateway ठेवतात, म्हणजे auth, throttling आणि logging एकाच तपासलेल्या जागी राहतात. पहिला review प्रश्न सोपा असतो: कोणते routes आहेत, आणि प्रत्येकाला कोण call करू शकतो?

⏭️ पुढे

Office तयार आहे. पण AWS तीन प्रकारची front offices देते — एक पूर्ण, एक हलके, आणि एक ज्यात phone line उघडी राहते.

git checkout lesson-02-rest-http-websocket

🛎️ Lesson 01 — Why an API gateway: the school's front office

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

📦 What's in this branch

The one idea behind the whole course: put one front office in front of every kitchen. It checks, counts, remembers and forwards every visitor, so each kitchen only has to cook. In AWS that office is Amazon API Gateway. Real files you will use all the way through:

apigw/gateway.py — the front office: a teaching model of an API Gateway REST API in pure Python (routes, {proxy+}, JWT and Lambda authorizers, API keys and usage plans, a token bucket, a stage cache, CORS, access logs, the 29 s timeout and the 10 MB limit)
apigw/demo.py — every lesson as a small program (python3 apigw/demo.py <section>), plus serve to open the office on localhost:8080
apigw/test_apigw.py — 12 checks on the office's rules
demo-output.txt — what a healthy run prints

🎒 Before you start: you need Python 3 and nothing else — no AWS account, no pip install. gateway.py is a teaching model: it follows the order and the defaults the AWS docs describe, but real API Gateway has many more settings. Its JWT check uses HS256 so it needs no crypto library; real JWT authorizers check RS256 signatures against the issuer's public keys. Commands marked on a real account need the AWS CLI and credentials; everything else runs here.

🧒 Explain like I'm 5

A big school has many kitchens 🍳 — one makes student records, one makes marks, one makes timetables. Visitors come all day: parents, teachers, apps, other schools.

Without a front office, every kitchen must do everything itself: check who the visitor is, count how many came, stop a crowd, write the visitor book, and cook. Every kitchen does it a little differently, and one of them always forgets.

So the school builds one front office 🛎️ at the gate. A clerk sits there. Every visitor stops at the desk first. The clerk:

checks the badge (who are you?),
counts visitors and stops a crowd at the door,
remembers common answers on a notice board,
writes every visit in the visitor book,
and forwards the visitor to the right kitchen — or says "no such kitchen".

The kitchens stay small and simple. That front office is an API gateway.

🗺️ Diagram

flowchart LR
    v["👪 visitors<br/>apps · browsers · partners"]
    office["🛎️ front office — API Gateway<br/>badge check · count · notice board · visitor book"]
    k1["🍳 kitchen: students<br/>GET /students/{id}"]
    k2["🍳 kitchen: marks<br/>POST /marks"]
    no["🚫 404 Not Found<br/>no such kitchen"]
    log["📒 visitor book<br/>metrics + access log"]
    v -->|"1 every request"| office
    office -->|"2 forward"| k1
    office -->|"2 forward"| k2
    office -.->|"no route"| no
    office -.->|"3 write it down"| log

🗺️ Drawn version + a lab: https://school-edh.pages.dev/apigateway/lesson-diagrams.html#l01

❓ What

API gateway — a managed service that sits in front of your back ends and handles the work every API needs: routing, authentication, throttling, caching, request validation, CORS, TLS, logging and metrics.
Amazon API Gateway — AWS's gateway. You describe routes (method + path), and for each one an integration (the kitchen: a Lambda function, an HTTP back end, another AWS service, or a mock).
Back end / integration — the code that makes the answer. In this course it is "the kitchen".
Managed — there are no servers for you to run. You pay per request (plus extras such as a cache), and AWS scales the office for you.
One front door, many back ends — the caller sees one address, for example https://api.school.example, even when five teams run five services behind it.

🤔 Why

Because auth, limits, logging and TLS are the same work for every service, and they are easy to get wrong. When each service builds them alone, one forgets the token expiry, another has no rate limit, a third logs nothing. A gateway does this work once, in one place, the same way for everyone. The kitchens then hold only business logic — and you can change the rules at the door without touching them.

🔧 How (in this repo)

office() in apigw/demo.py builds the school's gateway (school-api) with two stages (dev, prod) and eight routes. Gateway.handle() in apigw/gateway.py walks every request down the same line: CORS preflight → route match → API key → authorizer → throttle → validation → cache → integration → response mapping → access log. why() sends one good request and one request for a kitchen that does not exist. serve() puts the same office on http://localhost:8080 using only the standard library.

🧪 Try it

python3 apigw/demo.py why
python3 - <<'EOF'
import sys; sys.path.insert(0, "apigw"); from demo import office
gw, clock = office()
for p in ("/students/7", "/students/9", "/teachers"):
    st, headers, out = gw.handle("GET", p)
    print(st, p, out)
print(gw.metrics)
print(gw.logs[-1])
EOF
python3 apigw/test_apigw.py

Now open the office for real and knock on the door with curl:

python3 apigw/demo.py serve &          # the office opens on localhost:8080
sleep 1                                # give the office a second to open
curl -i localhost:8080/students/7
curl -i localhost:8080/students/7      # the same question again
curl -i localhost:8080/teachers
kill %1                                # close the office

✅ Verify — what you should see

why prints GET /students/7 → 200 {'id': '7', 'name': 'Aishwarya', 'class': '8B'} X-Cache: Miss and GET /teachers → 404 {'message': 'Not Found'}. Your snippet prints 200 for /students/7 and /students/9, 404 /teachers {'message': 'Not Found'}, then the counters {'Count': 3, '4XXError': 1, '5XXError': 0, 'CacheHitCount': 0, 'CacheMissCount': 2} and the last visitor-book line: {'requestId': 'req-0003', 'stage': 'prod', 'httpMethod': 'GET', 'path': '/teachers', 'status': 404, 'principal': None, 'latencyMs': 4, 'integrationLatencyMs': 0}. The tests end with 12/12 passed.

With the live office: the server prints front office open on http://localhost:8080 (stage prod) — Ctrl+C to close. The first curl shows HTTP/1.0 200 OK, X-Cache: Miss and {"id": "7", "name": "Aishwarya", "class": "8B"}; the second shows X-Cache: Hit — the office answered from its notice board. /teachers shows HTTP/1.0 404 Not Found and {"message": "Not Found"}.

🏁 What you just proved

Every visitor passes one desk. The desk answered, counted, remembered and wrote down each visit — and the kitchen was asked only when it had to be.

⚠️ Common mistakes

building auth, rate limits and logging again inside every service "because the gateway is extra"
thinking the gateway makes the back end secure by itself — it only checks what you configure
expecting a real REST API to say 404 for an unknown path: real REST APIs answer 403 {"message":"Missing Authentication Token"} for a path or method with no route (HTTP APIs answer 404 Not Found). This model says 404/405 to keep the lesson clear
treating gateway.py as the real service — it is a model; the AWS console's Test button and aws apigateway test-invoke-method are the referee

🏭 In production

On a real account — list your REST and HTTP APIs, and create an HTTP API in one command in front of an existing Lambda function ("quick create"):

aws apigateway get-rest-apis --query 'items[].{name:name,id:id}'
aws apigatewayv2 get-apis --query 'Items[].{name:Name,id:ApiId,type:ProtocolType}'
aws apigatewayv2 create-api --name school-api --protocol-type HTTP \
    --target arn:aws:lambda:ap-south-1:111122223333:function:students

🏭 Why this matters in production: most AWS serverless systems put API Gateway in front of Lambda so that auth, throttling and logging live in one reviewed place. The first review question is simple: which routes exist, and who may call each one?

⏭️ Next

The office exists. But AWS offers three kinds of front office — a full one, a lean one, and one where the phone line stays open.

git checkout lesson-02-rest-http-websocket

← Course homeall lessons Next →rest http websocket

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