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

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

📝 धडा 04 — Validation आणि mapping: form ची तपासणी आणि स्वच्छ उत्तर

📍 तुम्ही इथे आहात: 12 पैकी धडा 04 · मागे: lesson-03-routes-integrations · पुढे: lesson-05-stages-deployments

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

धडे 01–03, आणि office आत येताना आणि बाहेर जाताना करते ती दोन कामे: request validation (kitchen ला call करण्याआधीच चुकीची body 400 ने नाकारली जाते) आणि response mapping (office kitchen च्या उत्तरातून phone number काढून टाकते). apigw/demo.py मधले validate() दोन्ही दाखवते.

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

एक शिक्षिका clerk कडे एक marks form देते. Form मधले तीन रकाने भरलेले असायलाच हवेत: विद्यार्थी, विषय, mark. आणि mark हा आकडा असायला हवा.

Clerk form desk वरच ✍️ तपासतो. एखादा रकाना रिकामा आहे? "कृपया mark भरा." Mark अक्षरांत "नव्वद" असा लिहिला आहे? "Mark आकड्यातच हवा." Form शिक्षिकेकडे परत जातो — kitchen ला तो कधी दिसतच नाही, आणि त्यावर kitchen चा वेळही वाया जात नाही.

बाहेर जाताना, kitchen विद्यार्थ्याचे card परत पाठवते ज्यावर अजूनही phone number आहे. Card देण्याआधी clerk तो phone number झाकतो. Kitchen सोपे राहते; visitor ला फक्त त्याने पाहायला हवे तेवढेच दिसते.

🗺️ आकृती

flowchart LR
    t["👩‍🏫 POST /marks"] --> chk{"📝 form check<br/>required: student, subject, mark<br/>mark must be int"}
    chk -->|"mark missing"| e1["❌ 400 missing required field 'mark'"]
    chk -->|"mark = 'ninety'"| e2["❌ 400 'mark' must be int"]
    chk -->|"ok"| k["🍳 kitchen saves it → 201"]
    k2["🍳 GET /students/7<br/>id · name · class · phone"] --> map["✂️ response mapping<br/>remove phone"] --> out["📄 id · name · class"]

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

❓ काय

Request validation (REST APIs) — request validator body ला एका model (JSON Schema, draft 4) विरुद्ध तपासतो, आणि/किंवा आवश्यक query strings आणि headers आहेत का ते तपासतो. अपयश आल्यास {"message": "Invalid request body"} सह 400 परत येतो आणि integration ला call केले जात नाही.
Model — body साठीचे JSON Schema: आवश्यक fields, types, लांबी, patterns.
Mapping templates (REST APIs, custom / non-proxy integrations) — VTL मधले छोटे programs, जे back end ला दिसण्याआधी request, किंवा caller ला दिसण्याआधी response नव्याने मांडतात. Proxy integration मध्ये templates नसतात: request जशीच्या तशी जाते आणि back end पूर्ण response बनवतो.
HTTP APIs मध्ये request validation नाही आणि VTL नाही; ते सोपे parameter mapping देतात (headers, query strings आणि paths जोडणे, बदलणे किंवा काढणे).
Gateway responses — office ची स्वतःची error उत्तरे (BAD_REQUEST_BODY, UNAUTHORIZED, THROTTLED …). त्यांची body आणि headers तुम्ही बदलू शकता, उदा. $context.error.validationErrorString समाविष्ट करण्यासाठी.

🤔 का

कारण kitchen पर्यंत पोहोचलेल्या चुकीच्या form ची किंमत म्हणजे एक Lambda run, कदाचित एक database call, आणि caller साठी गोंधळात टाकणारा 500. दारावरच आकार तपासला की स्पष्ट 400 मिळतो, back end कचऱ्यापासून सुरक्षित राहतो, आणि प्रत्येक client साठी एकच लिखित करार (model) राहतो. Response mapping मुळे खाजगी fields — phone numbers, आतले ids — फक्त back end ने परत दिले म्हणून बाहेर जात नाहीत.

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

apigw/gateway.py मधले validate(schema, body) हे एक छोटेसे JSON-schema आहे: required fields आणि types. office() मधल्या POST /marks route ला schema={"required": ["student", "subject", "mark"], "types": {"mark": int}} आहे. Gateway._handle() मध्ये validation integration च्या आधी चालते, त्यामुळे चुकीची body कधीच add_mark() पर्यंत पोहोचत नाही. GET /students/{id} route ला mapping=hide_phone आहे, जे kitchen च्या उत्तरावर बाहेर जाताना लागू होते — custom integration वरच्या response mapping template ची model मधली आवृत्ती. Students kitchen ला खरोखर किती वेळा call केले ते calls["n"] मोजते.

🧪 करून पाहा

python3 apigw/demo.py validate
python3 - <<'EOF'
import sys; sys.path.insert(0, "apigw"); from demo import office, token, calls
from gateway import validate
gw, c = office()
H = {"Authorization": "Bearer " + token(c, scope="marks:write")}
for body in (["7", "maths", 91], {"student": "7", "subject": "maths", "mark": 91.5}, None):
    print(gw.handle("POST", "/marks", H, body)[0::2])
schema = {"required": ["student", "subject", "mark"], "types": {"mark": int}}
print(validate(schema, {"student": "7", "subject": "maths"}))
calls["n"] = 0; gw.handle("GET", "/students/9"); print("kitchen calls:", calls["n"], "· answer:", gw.handle("GET", "/students/9")[2])
EOF

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

validate दोन नकार आणि एक यश print करते: POST /marks → 400 {'message': 'Invalid request body', 'why': "missing required field 'mark'"}, POST /marks → 400 {'message': 'Invalid request body', 'why': "'mark' must be int"}, POST /marks → 201 {'saved': {'student': '7', 'subject': 'maths', 'mark': 91}, 'table': 'marks-prod'}. मग mapping: kitchen: {'id': '7', 'name': 'Aishwarya', 'class': '8B', 'phone': '98xxxxxx12'} आणि GET /students/7 → 200 {'id': '7', 'name': 'Aishwarya', 'class': '8B'} — phone नाही.

तुमचा snippet list साठी (400, {'message': 'Invalid request body', 'why': 'body must be a JSON object'}), 91.5 साठी (400, {'message': 'Invalid request body', 'why': "'mark' must be int"}), body नसताना पुन्हा body must be a JSON object, मग missing required field 'mark', आणि kitchen calls: 1 · answer: {'id': '9', 'name': 'Katrina', 'class': '9A'} print करतो.

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

चुकीचा form कारणासह desk वरच नाकारला जातो, त्यासाठी kitchen ला call होत नाही, आणि kitchen न बदलता बाहेर जाताना उत्तर स्वच्छ करता येते.

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

body साठी validation चालू केले पण model सैल आहे (required नाही) — सगळे काही पास होते
business नियम ("या विषयासाठी mark जास्तीत जास्त 100") VTL मध्ये टाकणे — templates आकारासाठी ठेवा, logic code मध्ये
proxy integration वर mapping templates ची अपेक्षा करणे — तिथे ते लागू होत नाहीत
response mapping मध्ये field लपवणे आणि तरीही back end चे पूर्ण उत्तर log करणे

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

On a real account — REST API साठी OpenAPI मधले model आणि validator:

x-amazon-apigateway-request-validators:
  body-only: { validateRequestBody: true, validateRequestParameters: false }
paths:
  /marks:
    post:
      x-amazon-apigateway-request-validator: body-only
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [student, subject, mark]
              properties:
                student: { type: string }
                subject: { type: string }
                mark:    { type: integer, minimum: 0, maximum: 100 }

Phone काढून टाकणारे, custom Lambda integration वरचे response mapping template (VTL):

#set($s = $input.path('$'))
{ "id": "$s.id", "name": "$s.name", "class": "$s.class" }

🏭 Production मध्ये हे का महत्त्वाचे: request validation partners ना स्पष्ट 400 देते आणि database पासून कचरा दूर ठेवते; fields बाहेर जाण्याविरुद्ध response mapping ही शेवटची फळी आहे. दोन्ही aws apigateway test-invoke-method ने test करा.

⏭️ पुढे

Desk चालतो. खरा शाळेचा दिवस न बिघडवता तो कसा बदलायचा? Stages आणि deployments — रंगीत तालीम आणि खरा प्रयोग.

git checkout lesson-05-stages-deployments

📝 Lesson 04 — Validation & mapping: the form check and the clean answer

📍 You are here: Lesson 04 of 12 · Previous: lesson-03-routes-integrations · Next: lesson-05-stages-deployments

📦 What's in this branch

Lessons 01–03, plus two jobs the office does on the way in and the way out: request validation (a bad body is refused with 400 before the kitchen is called) and response mapping (the office removes the phone number from the kitchen's answer). validate() in apigw/demo.py shows both.

🧒 Explain like I'm 5

A teacher hands a marks form to the clerk. The form must have three boxes filled: student, subject, mark. And the mark must be a number.

The clerk checks the form at the desk ✍️. A box is empty? "Please fill in the mark." The mark says "ninety" in words? "The mark must be a number." The form goes back to the teacher — the kitchen never sees it, and never wastes time on it.

On the way out, the kitchen sends back a student card that still has the phone number on it. The clerk covers the phone number before handing the card over. The kitchen stays simple; the visitor sees only what they should.

🗺️ Diagram

flowchart LR
    t["👩‍🏫 POST /marks"] --> chk{"📝 form check<br/>required: student, subject, mark<br/>mark must be int"}
    chk -->|"mark missing"| e1["❌ 400 missing required field 'mark'"]
    chk -->|"mark = 'ninety'"| e2["❌ 400 'mark' must be int"]
    chk -->|"ok"| k["🍳 kitchen saves it → 201"]
    k2["🍳 GET /students/7<br/>id · name · class · phone"] --> map["✂️ response mapping<br/>remove phone"] --> out["📄 id · name · class"]

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

❓ What

Request validation (REST APIs) — a request validator checks the body against a model (a JSON Schema, draft 4), and/or checks that required query strings and headers are present. A failure returns 400 with {"message": "Invalid request body"} and the integration is not called.
Model — the JSON Schema for a body: required fields, types, lengths, patterns.
Mapping templates (REST APIs, custom / non-proxy integrations) — small programs in VTL that reshape the request before the back end sees it, or the response before the caller sees it. With a proxy integration there are no templates: the request passes as-is and the back end builds the whole response.
HTTP APIs have no request validation and no VTL; they offer simpler parameter mapping (add, change or remove headers, query strings and paths).
Gateway responses — the office's own error answers (BAD_REQUEST_BODY, UNAUTHORIZED, THROTTLED …). You can change their body and headers, e.g. to include $context.error.validationErrorString.

🤔 Why

Because a bad form that reaches the kitchen costs a Lambda run, maybe a database call, and a confusing 500 for the caller. Checking the shape at the door gives a clear 400, protects the back end from junk, and keeps one written contract (the model) for every client. Response mapping keeps private fields — phone numbers, internal ids — from leaking just because the back end returned them.

🔧 How (in this repo)

validate(schema, body) in apigw/gateway.py is a tiny JSON-schema: required fields and types. The route POST /marks in office() has schema={"required": ["student", "subject", "mark"], "types": {"mark": int}}. In Gateway._handle() validation runs before the integration, so a bad body never reaches add_mark(). The route GET /students/{id} has mapping=hide_phone, applied to the kitchen's answer on the way out — the model's version of a response mapping template on a custom integration. calls["n"] counts how often the students kitchen was really called.

🧪 Try it

python3 apigw/demo.py validate
python3 - <<'EOF'
import sys; sys.path.insert(0, "apigw"); from demo import office, token, calls
from gateway import validate
gw, c = office()
H = {"Authorization": "Bearer " + token(c, scope="marks:write")}
for body in (["7", "maths", 91], {"student": "7", "subject": "maths", "mark": 91.5}, None):
    print(gw.handle("POST", "/marks", H, body)[0::2])
schema = {"required": ["student", "subject", "mark"], "types": {"mark": int}}
print(validate(schema, {"student": "7", "subject": "maths"}))
calls["n"] = 0; gw.handle("GET", "/students/9"); print("kitchen calls:", calls["n"], "· answer:", gw.handle("GET", "/students/9")[2])
EOF

✅ Verify — what you should see

validate prints two refusals and one success: POST /marks → 400 {'message': 'Invalid request body', 'why': "missing required field 'mark'"}, POST /marks → 400 {'message': 'Invalid request body', 'why': "'mark' must be int"}, POST /marks → 201 {'saved': {'student': '7', 'subject': 'maths', 'mark': 91}, 'table': 'marks-prod'}. Then the mapping: kitchen: {'id': '7', 'name': 'Aishwarya', 'class': '8B', 'phone': '98xxxxxx12'} and GET /students/7 → 200 {'id': '7', 'name': 'Aishwarya', 'class': '8B'} — no phone.

Your snippet prints (400, {'message': 'Invalid request body', 'why': 'body must be a JSON object'}) for the list, (400, {'message': 'Invalid request body', 'why': "'mark' must be int"}) for 91.5, body must be a JSON object again for no body, then missing required field 'mark', and kitchen calls: 1 · answer: {'id': '9', 'name': 'Katrina', 'class': '9A'}.

🏁 What you just proved

A bad form is refused at the desk with a reason, the kitchen is not called for it, and the answer can be cleaned on the way out without changing the kitchen.

⚠️ Common mistakes

validation turned on for the body but the model is loose (no required) — everything passes
putting business rules ("a mark is at most 100 for this subject") into VTL — keep templates for shape, logic in code
expecting mapping templates on a proxy integration — they do not apply there
hiding a field in the response mapping and then logging the full back-end answer anyway

🏭 In production

On a real account — a model and a validator in OpenAPI for a REST API:

x-amazon-apigateway-request-validators:
  body-only: { validateRequestBody: true, validateRequestParameters: false }
paths:
  /marks:
    post:
      x-amazon-apigateway-request-validator: body-only
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [student, subject, mark]
              properties:
                student: { type: string }
                subject: { type: string }
                mark:    { type: integer, minimum: 0, maximum: 100 }

A response mapping template (VTL) on a custom Lambda integration that drops the phone:

#set($s = $input.path('$'))
{ "id": "$s.id", "name": "$s.name", "class": "$s.class" }

🏭 Why this matters in production: request validation gives partners a clear 400 and keeps junk away from the database; response mapping is a last line against leaking fields. Test both with aws apigateway test-invoke-method.

⏭️ Next

The desk works. How do you change it without breaking the real school day? Stages and deployments — the rehearsal and the real show.

git checkout lesson-05-stages-deployments

← Previousroutes integrations Next →stages deployments

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