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

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

🗺️ धडा 03 — Routes आणि integrations: कोणता desk, कोणते kitchen

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

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

धडे 01–02, आणि office desk कसा निवडते: path parameters ({id}), सगळे पकडणारे {proxy+}, ANY method, "सर्वात नेमका route जिंकतो" हा नियम, आणि integration — office visitor ला कुठे पुढे पाठवते ते. apigw/demo.py मधले routes() प्रत्येक नियम दाखवते.

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

Front office मध्ये desks चा एक फलक आहे:

"विद्यार्थी, क्रमांक ___" — रिकाम्या जागेत कोणताही क्रमांक बसतो (/students/{id}).
"विद्यार्थी, मी" — फक्त "मला माझ्याबद्दल सांगा" यासाठीचा desk (/students/me).
"Files, याच्यानंतर काहीही" — प्रत्येक folder मधल्या प्रत्येक file साठी एकच desk (/files/{proxy+}).

एक visitor म्हणतो "विद्यार्थी, मी". दोन desks बसू शकतात: "विद्यार्थी, क्रमांक ___" (रिकामी जागा = "मी") आणि "विद्यार्थी, मी". Clerk नेहमी त्याला जास्त नेमक्या desk कडे पाठवतो. ठरलेला शब्द रिकाम्या जागेवर जिंकतो, आणि "काहीही" desk ही शेवटची निवड असते.

आणि जर visitor ने फक्त नोंदी वाचणाऱ्या desk वर विद्यार्थ्याची नोंद फेकून द्यायला सांगितले तर? Desk आहे, पण त्या कामासाठी नाही: "परवानगी नाही".

प्रत्येक desk ला एका kitchen कडे जाणारे दार आहे — ते दार म्हणजे integration.

🗺️ आकृती

flowchart LR
    r1["GET /students/me"] -->|"fixed word wins"| d1["🪑 /students/me<br/>→ me() · JWT"]
    r2["GET /students/9"] -->|"id = 9"| d2["🪑 /students/{id}<br/>→ get_student()"]
    r3["GET /files/term1/maths/paper.pdf"] -->|"proxy = term1/maths/paper.pdf"| d3["🪑 /files/{proxy+}<br/>→ files()"]
    r4["DELETE /students/9"] -->|"path fits, method does not"| d4["🚫 405 Method Not Allowed"]
    d2 --> k["🍳 integration<br/>Lambda · HTTP · AWS service · mock · VPC link"]

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

❓ काय

Route — method अधिक path, उदा. GET /students/{id}. REST API मध्ये path चे भाग म्हणजे resources आणि प्रत्येकाला methods असतात; HTTP API मध्ये route एकाच string म्हणून लिहिला जातो, GET /students/{id}.
Path parameter — {id} हे path चा एक segment जुळवते (/ नाही). ती value back end पर्यंत पोहोचते, उदा. id = 9.
Greedy path variable — {proxy+} त्याच्यानंतरचे सगळे जुळवते, slashes सह. तो path चा शेवटचा भाग असायलाच हवा.
ANY — GET, POST, PUT, DELETE आणि बाकी सगळे पकडणारी एकच method. ANY /{proxy+} प्रत्येक request एकाच back end कडे पाठवते (web frameworks सह हे नेहमीचे आहे). HTTP APIs मध्ये, इतर कोणताही route जुळत नाही त्या सगळ्यासाठी $default route सुद्धा असतो.
सर्वात नेमका जिंकतो — ठरलेला segment {param} वर जिंकतो, आणि greedy {proxy+} हा शेवटचा पर्याय असतो.
Integration — office कुठे पुढे पाठवते:
- Lambda — proxy (पूर्ण request event म्हणून आत जाते; function पूर्ण response बनवते) किंवा custom (office input आणि output नव्याने मांडते — धडा 04);
- HTTP — proxy किंवा custom, कोणत्याही public HTTP back end कडे;
- AWS service — उदा. DynamoDB, SQS किंवा Step Functions ला थेट call करा;
- mock — office स्वतःच उत्तर देते (tests आणि CORS preflights साठी सोयीचे);
- VPC link — तुमच्या VPC मधल्या load balancer कडे private integration.

🤔 का

कारण चुकीचा route हा शांत bug असतो: request चुकीच्या desk वर पोहोचते आणि कोणालाही error दिसत नाही. {id} desk ने हाताळलेला /students/me "me" नावाचा विद्यार्थी शोधतो. आणि ANY /{proxy+} सोयीचे आहे, पण back end ने तपासले नाही तर ते /admin/... सुद्धा back end कडे पाठवते. प्रत्येक path ला नेमका कोणता desk उत्तर देतो ते माहीत ठेवा.

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

apigw/gateway.py मधले compile_path() हे {id} ला "एक segment" आणि {proxy+} ला "उरलेले सगळे" मध्ये बदलते. Gateway.match() path जुळणारे प्रत्येक route गोळा करते, योग्य method (किंवा ANY) असलेले ठेवते, आणि सर्वात नेमका निवडते (Route.specificity()): कोणताही path जुळला नाही → 404, path जुळला पण method नाही → 405. Integration म्हणजे एक Python function, ज्याला params, query, body, principal आणि stageVariables सह एक event मिळतो — Lambda proxy event सारखीच आकाराची कल्पना.

🧪 करून पाहा

python3 apigw/demo.py routes
python3 - <<'EOF'
import sys; sys.path.insert(0, "apigw"); from demo import office
from gateway import Route
gw, _ = office()
for m, p in [("GET", "/students/9"), ("GET", "/students/me"), ("GET", "/files/term1/maths/paper.pdf"), ("GET", "/files/"), ("DELETE", "/students/9"), ("GET", "/students/9/marks")]:
    r, params, code = gw.match(m, p)
    print(f"{m:<6} {p:<30} → {code} {r.path if r else None} {params}")
gw.add(Route("ANY", "/library/{proxy+}", lambda e: (200, {"method": e["method"], "rest": e["params"]["proxy"]})))
for m in ("GET", "DELETE"):
    print(m, gw.handle(m, "/library/books/42")[2])
EOF

आणि चालू office वर:

python3 apigw/demo.py serve &
sleep 1                                # give the office a second to open
curl localhost:8080/files/term1/maths/paper.pdf
curl -i -X DELETE localhost:8080/students/9
kill %1

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

routes हे GET /students/9 → 200 {'id': '9', 'name': 'Katrina', 'class': '9A'}, GET /students/me → 200 {'you': 'teacher-42'}, GET /files/term1/maths/paper.pdf → 200 {'file': 'term1/maths/paper.pdf'} आणि DELETE /students/9 → 405 {'message': 'Method Not Allowed'} print करते.

तुमचा snippet हे print करतो:

GET    /students/9                    → 200 /students/{id} {'id': '9'}
GET    /students/me                   → 200 /students/me {}
GET    /files/term1/maths/paper.pdf   → 200 /files/{proxy+} {'proxy': 'term1/maths/paper.pdf'}
GET    /files/                        → 404 None None
DELETE /students/9                    → 405 None None
GET    /students/9/marks              → 404 None None
GET {'method': 'GET', 'rest': 'books/42'}
DELETE {'method': 'DELETE', 'rest': 'books/42'}

{proxy+} ला किमान एक character लागतो (/files/ → 404), {id} कधीच / घेत नाही (/students/9/marks → 404), आणि ANY ने GET आणि DELETE दोन्ही घेतले. चालू office {"file": "term1/maths/paper.pdf"} आणि HTTP/1.0 405 Method Not Allowed असे उत्तर देते.

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

कोणत्याही path साठी desk कोणता ते तुम्ही आधीच सांगू शकता: ठरलेला शब्द {id} वर जिंकतो, {proxy+} उरलेले घेतो, आणि जुळणारा path पण चुकीची method म्हणजे 405, 404 नाही.

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

/students/me शिवाय /students/{id} — "me" हा student id बनतो
कोणालाही publish करायचे नव्हते असे admin paths असलेल्या app समोर ANY /{proxy+}
Lambda proxy integration ने {"statusCode": 200, "headers": {...}, "body": "..."} ऐवजी साधी dict परत करणे — caller ला 502 Internal server error मिळतो
खऱ्या REST API चा 403 Missing Authentication Token हा auth चा प्रश्न समजणे — त्याचा अर्थ सहसा "असा route किंवा method नाही" असा असतो

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

On a real account — तेच routes API Gateway extensions सह OpenAPI मध्ये (aws apigateway import-rest-api --body fileb://school.yaml ने import करा):

openapi: 3.0.1
info: { title: school-api, version: "1" }
paths:
  /students/{id}:
    get:
      parameters: [{ name: id, in: path, required: true, schema: { type: string } }]
      x-amazon-apigateway-integration:
        type: aws_proxy
        httpMethod: POST
        uri: arn:aws:apigateway:ap-south-1:lambda:path/2015-03-31/functions/arn:aws:lambda:ap-south-1:111122223333:function:students/invocations
  /files/{proxy+}:
    x-amazon-apigateway-any-method:
      x-amazon-apigateway-integration:
        type: http_proxy
        httpMethod: ANY
        uri: https://files.internal.school.example/{proxy}
        requestParameters: { integration.request.path.proxy: method.request.path.proxy }

Client शिवाय एक route test करा: aws apigateway test-invoke-method --rest-api-id abc123 --resource-id r1s2t3 --http-method GET --path-with-query-string /students/9.

🏭 Production मध्ये हे का महत्त्वाचे: routes code मध्ये ठेवा (OpenAPI, SAM, Terraform), code सारखेच त्यांचे review करा, आणि back end कडे publish करू नयेत असे paths असतील तेव्हा catch-all ऐवजी नेमके routes वापरा.

⏭️ पुढे

योग्य desk सापडला. पण visitor चा form चुकीचा असेल तर? Validation आणि mapping — kitchen ला दिसण्याआधीच चुकीचा form नाकारा.

git checkout lesson-04-mapping-validation

🗺️ Lesson 03 — Routes & integrations: which desk, which kitchen

📍 You are here: Lesson 03 of 12 · Previous: lesson-02-rest-http-websocket · Next: lesson-04-mapping-validation

📦 What's in this branch

Lessons 01–02, plus how the office picks a desk: path parameters ({id}), the greedy {proxy+}, the ANY method, the rule "the most specific route wins", and the integration — where the office forwards the visitor. routes() in apigw/demo.py shows each rule.

🧒 Explain like I'm 5

The front office has a board of desks:

"Students, number ___" — any number fits the blank (/students/{id}).
"Students, ME" — a desk just for "tell me about myself" (/students/me).
"Files, anything after this" — one desk for every file in every folder (/files/{proxy+}).

A visitor says "Students, me". Two desks could fit: "Students, number ___" (with the blank = "me") and "Students, ME". The clerk always sends them to the more exact desk. A fixed word beats a blank, and the "anything" desk is the last choice.

And if the visitor asks to throw away a student record at a desk that only reads records? The desk exists, but not for that job: "not allowed".

Each desk has a door to one kitchen — that door is the integration.

🗺️ Diagram

flowchart LR
    r1["GET /students/me"] -->|"fixed word wins"| d1["🪑 /students/me<br/>→ me() · JWT"]
    r2["GET /students/9"] -->|"id = 9"| d2["🪑 /students/{id}<br/>→ get_student()"]
    r3["GET /files/term1/maths/paper.pdf"] -->|"proxy = term1/maths/paper.pdf"| d3["🪑 /files/{proxy+}<br/>→ files()"]
    r4["DELETE /students/9"] -->|"path fits, method does not"| d4["🚫 405 Method Not Allowed"]
    d2 --> k["🍳 integration<br/>Lambda · HTTP · AWS service · mock · VPC link"]

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

❓ What

Route — a method plus a path, e.g. GET /students/{id}. In a REST API the path parts are resources and each has methods; in an HTTP API a route is written as one string, GET /students/{id}.
Path parameter — {id} matches one path segment (no /). The value reaches the back end, e.g. id = 9.
Greedy path variable — {proxy+} matches everything after it, slashes included. It must be the last part of the path.
ANY — one method that catches GET, POST, PUT, DELETE and the rest. ANY /{proxy+} sends every request to one back end (common with web frameworks). HTTP APIs also have a $default route for anything no other route matches.
Most specific wins — a fixed segment beats a {param}, and a greedy {proxy+} is the last resort.
Integration — where the office forwards:
- Lambda — proxy (the whole request goes in as an event; the function builds the full response) or custom (the office reshapes input and output — lesson 04);
- HTTP — proxy or custom, to any public HTTP back end;
- AWS service — call e.g. DynamoDB, SQS or Step Functions directly;
- mock — the office answers itself (handy for tests and CORS preflights);
- VPC link — a private integration to a load balancer inside your VPC.

🤔 Why

Because a wrong route is a quiet bug: the request lands on the wrong desk and nobody sees an error. /students/me handled by the {id} desk looks up a student called "me". And ANY /{proxy+} is convenient, but it also sends /admin/... to the back end unless the back end checks it. Know exactly which desk answers each path.

🔧 How (in this repo)

compile_path() in apigw/gateway.py turns {id} into "one segment" and {proxy+} into "the rest". Gateway.match() collects every route whose path fits, keeps those with the right method (or ANY), and picks the most specific (Route.specificity()): no fitting path → 404, a fitting path but no fitting method → 405. The integration is a Python function that receives an event with params, query, body, principal and stageVariables — the same shape idea as a Lambda proxy event.

🧪 Try it

python3 apigw/demo.py routes
python3 - <<'EOF'
import sys; sys.path.insert(0, "apigw"); from demo import office
from gateway import Route
gw, _ = office()
for m, p in [("GET", "/students/9"), ("GET", "/students/me"), ("GET", "/files/term1/maths/paper.pdf"), ("GET", "/files/"), ("DELETE", "/students/9"), ("GET", "/students/9/marks")]:
    r, params, code = gw.match(m, p)
    print(f"{m:<6} {p:<30} → {code} {r.path if r else None} {params}")
gw.add(Route("ANY", "/library/{proxy+}", lambda e: (200, {"method": e["method"], "rest": e["params"]["proxy"]})))
for m in ("GET", "DELETE"):
    print(m, gw.handle(m, "/library/books/42")[2])
EOF

And on the live office:

python3 apigw/demo.py serve &
sleep 1                                # give the office a second to open
curl localhost:8080/files/term1/maths/paper.pdf
curl -i -X DELETE localhost:8080/students/9
kill %1

✅ Verify — what you should see

routes prints GET /students/9 → 200 {'id': '9', 'name': 'Katrina', 'class': '9A'}, GET /students/me → 200 {'you': 'teacher-42'}, GET /files/term1/maths/paper.pdf → 200 {'file': 'term1/maths/paper.pdf'} and DELETE /students/9 → 405 {'message': 'Method Not Allowed'}.

Your snippet prints:

GET    /students/9                    → 200 /students/{id} {'id': '9'}
GET    /students/me                   → 200 /students/me {}
GET    /files/term1/maths/paper.pdf   → 200 /files/{proxy+} {'proxy': 'term1/maths/paper.pdf'}
GET    /files/                        → 404 None None
DELETE /students/9                    → 405 None None
GET    /students/9/marks              → 404 None None
GET {'method': 'GET', 'rest': 'books/42'}
DELETE {'method': 'DELETE', 'rest': 'books/42'}

{proxy+} needs at least one character (/files/ → 404), {id} never takes a / (/students/9/marks → 404), and ANY took both GET and DELETE. The live office answers {"file": "term1/maths/paper.pdf"} and HTTP/1.0 405 Method Not Allowed.

🏁 What you just proved

You can predict the desk for any path: a fixed word beats {id}, {proxy+} takes the rest, and a path that fits with the wrong method is a 405, not a 404.

⚠️ Common mistakes

/students/{id} without /students/me — "me" becomes a student id
ANY /{proxy+} in front of an app that has admin paths nobody meant to publish
a Lambda proxy integration that returns a plain dict instead of {"statusCode": 200, "headers": {...}, "body": "..."} — the caller gets 502 Internal server error
reading a real REST API's 403 Missing Authentication Token as an auth problem — it usually means "no such route or method"

🏭 In production

On a real account — the same routes in OpenAPI with API Gateway extensions (import with aws apigateway import-rest-api --body fileb://school.yaml):

openapi: 3.0.1
info: { title: school-api, version: "1" }
paths:
  /students/{id}:
    get:
      parameters: [{ name: id, in: path, required: true, schema: { type: string } }]
      x-amazon-apigateway-integration:
        type: aws_proxy
        httpMethod: POST
        uri: arn:aws:apigateway:ap-south-1:lambda:path/2015-03-31/functions/arn:aws:lambda:ap-south-1:111122223333:function:students/invocations
  /files/{proxy+}:
    x-amazon-apigateway-any-method:
      x-amazon-apigateway-integration:
        type: http_proxy
        httpMethod: ANY
        uri: https://files.internal.school.example/{proxy}
        requestParameters: { integration.request.path.proxy: method.request.path.proxy }

Test one route without a client: aws apigateway test-invoke-method --rest-api-id abc123 --resource-id r1s2t3 --http-method GET --path-with-query-string /students/9.

🏭 Why this matters in production: keep routes in code (OpenAPI, SAM, Terraform), review them like code, and prefer exact routes over a catch-all when the back end has paths it should not publish.

⏭️ Next

The right desk is found. But what if the visitor's form is wrong? Validation and mapping — reject a bad form before the kitchen sees it.

git checkout lesson-04-mapping-validation

← Previousrest http websocket Next →mapping validation

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