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

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

📋 धडा 04 — JSON आणि schemas: प्रमाणित फॉर्म

📍 तुम्ही इथे आहात: 12 पैकी धडा 04 · मागे: lesson-03-rest-resources · पुढे: lesson-05-build-an-api

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

धडे 01–03, आणि त्यासोबत प्रत्यक्ष form: JSON bodies, वाईट forms कारणासह नाकारणारे validation, आणि OpenAPI — counter स्वीकारतो त्या प्रत्येक form चा छापलेला कॅटलॉग. खरी file:

api/openapi.yaml — कॅटलॉग

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

Counter खरडलेल्या चिठ्ठ्या स्वीकारत नाही. विद्यार्थ्याचे नाव नोंदवायचे तर तुम्ही प्रमाणित form 📋 भरता:

{"name": "Zoya", "class": "3B", "grade": "A"}

Archive कडे जाण्याच्या आधी clerk तो तपासतो: name भरले आहे का? class आपल्याकडे खरोखर असलेल्या वर्गांपैकी एक आहे का (3A, 3B)? grade अस्तित्वात असलेल्या grades पैकी एक आहे का? नसेल तर slip लगेच 400 शिक्का आणि नेमके काय चुकले याची field-वार यादी घेऊन परत येते — खांदे उडवणे नाही, 500 नाही, "काहीतरी चुकले" नाही.

आणि forms कसे दिसतात याचा कोणालाच अंदाज लावावा लागू नये म्हणून office त्यांचा कॅटलॉग छापते — प्रत्येक path, प्रत्येक parameter, प्रत्येक field, प्रत्येक शिक्का — OpenAPI नावाच्या प्रमाणित रचनेत. माणसे तो वाचतात; साधने त्यातून documentation, client libraries आणि tests तयार करतात.

🗺️ आकृती

flowchart LR
    form["📋 the form (JSON)<br/>name · class ∈ {3A,3B} · grade?"]
    val["✅ validate()<br/>required? type? allowed value?"]
    ok["201 Created<br/>Location: /v1/students/6"]
    bad["400 validation_failed<br/>problems: [{field, problem}, …]"]
    form -->|"1"| val
    val -->|"2 fine"| ok
    val -.->|"2 not fine"| bad
    cat["📚 openapi.yaml — the catalogue<br/>paths · params · schemas · errors"]
    cat -.->|"3 describes all of it"| form

❓ काय

JSON: objects {}, arrays [], strings, numbers, booleans, null. Comments नाहीत, शेवटचे जादा स्वल्पविराम नाहीत, dates नाहीत (त्या strings असतात — ISO 8601 वर एकमत करा). दोन्ही बाजूंना Content-Type: application/json.
Validation counter वर होते, archive मध्ये नाही: आवश्यक fields, types, चालणाऱ्या किमती (enum), मर्यादा, formats. 400 आणि problems यादी देऊन नाकारा; अर्धवट-बरोबर form कधीच storage पर्यंत पोहोचू देऊ नका.
Schema: form चा लिखित आकार. OpenAPI मध्ये तो JSON Schema असतो: type, required, enum, minLength, default.
OpenAPI (api/openapi.yaml): paths → operations → parameters, requestBody, responses; सामायिक forms साठी components/schemas (Student, StudentInput, Error). एक file संपूर्ण counter चे वर्णन करते; धडा 12 ती docs आणि tests साठी वापरतो.
Output सुद्धा एक form आहे: तुम्ही परत देता त्या field नावांवर आणि types वर clients अवलंबून असतात. Field जोडणे सुरक्षित आहे; ते काढणे किंवा त्याचे नाव बदलणे नाही (धडा 09).

🤔 का

कारण archive हा महागडा भाग आहे. Counter वर तपासलेल्या form ला microseconds लागतात; database मध्ये लिहिलेल्या वाईट row मुळे data ची साफसफाई करावी लागते, आणि जिथे 400 हवा तिथे 500 दिल्याने on-call engineer चा एक तास जातो. कॅटलॉग हा दुसरा अर्धा भाग आहे: लिखित contract नसलेले API म्हणजे फक्त अफवा.

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

school_api.py मधले validate_student(body) {field, problem} dicts ची यादी परत देते; यादी रिकामी नसेल तेव्हा do_POST आणि do_PUT 400 validation_failed ने नाकारतात. त्याची ओळ-ओळ तुलना api/openapi.yaml मधल्या StudentInput शी करा — ते नेहमी जुळलेच पाहिजेत.

🧪 करून पाहा

K='X-API-Key: hall-pass-123'; B=http://127.0.0.1:8080/v1; J='Content-Type: application/json'
curl -s -X POST $B/students -H "$K" -H "$J" -d '{"name":"","class":"9Z"}'        # 400 with two problems
curl -s -X POST $B/students -H "$K" -H "$J" -d '{"name":"Zoya","class":"3B"}'    # 201; grade defaults to C
curl -s -X POST $B/students -H "$K" -H "$J" -d '{"name":"Zoya","class":"3B","grade":"Z"}'   # 400: grade
# now change the contract: add a required "roll_no" field to validate_student() AND openapi.yaml, restart, retest

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

पहिला call name आणि class यांची नावे असलेल्या problems सह 400 परत देतो; दुसरा 201 आणि "grade": "C" असलेली body देतो; तिसरा grade चे नाव सांगतो. तुमचा roll_no बदल केल्यानंतर, तुम्ही ते field जोडेपर्यंत दुसरा call अयशस्वी होतो — आणि कॅटलॉग का ते सांगतो.

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

कोणतेही काम होण्याआधीच counter वाईट forms field-पातळीवरच्या कारणासह नाकारतो, आणि कॅटलॉग व code एकाच form चे वर्णन करतात.

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

counter ऐवजी database मध्ये validation करणे — constraint error चा 500 होतो
प्रत्येक चुकीसाठी एकच error संदेश ("invalid input") — कोणते field आणि का ते सांगा
code पासून दूर जाणारा कॅटलॉग — एकातून दुसरे generate करा, किंवा एकमेकांविरुद्ध test करा (धडा 12)
dates new Date() strings म्हणून पाठवणे — ISO 8601 आणि time zones वर एकमत करा

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: contract-first teams OpenAPI file मधून client SDKs, mocks आणि tests generate करतात, त्यामुळे frontend आणि backend एकाच वेळी बांधले जातात. Contract नसलेल्या teams ना field ची नावे Slack मध्ये कळतात.

⏭️ पुढे

आता counter उघडून प्रत्येक ओळ वाचायची वेळ: API बांधा — school_api.py चे चार भाग.

git checkout lesson-05-build-an-api

📋 Lesson 04 — JSON & schemas: the standard form

📍 You are here: Lesson 04 of 12 · Previous: lesson-03-rest-resources · Next: lesson-05-build-an-api

📦 What's in this branch

Lessons 01–03, plus the form itself: JSON bodies, validation that refuses bad forms with a reason, and OpenAPI — the printed catalogue of every form the counter accepts. Real file:

api/openapi.yaml — the catalogue

🧒 Explain like I'm 5

The counter does not accept scribbled notes. To enrol a student you fill in the standard form 📋:

{"name": "Zoya", "class": "3B", "grade": "A"}

The clerk checks it before walking to the archive: is name filled in? is class one of the classes we actually have (3A, 3B)? is grade one of the grades that exist? If not, the slip comes straight back with a 400 stamp and a list of exactly what is wrong, field by field — not a shrug, not a 500, not "something went wrong".

And so nobody has to guess what the forms look like, the office prints a catalogue of them — every path, every parameter, every field, every stamp — in a standard layout called OpenAPI. Humans read it; tools turn it into documentation, client libraries and tests.

🗺️ Diagram

flowchart LR
    form["📋 the form (JSON)<br/>name · class ∈ {3A,3B} · grade?"]
    val["✅ validate()<br/>required? type? allowed value?"]
    ok["201 Created<br/>Location: /v1/students/6"]
    bad["400 validation_failed<br/>problems: [{field, problem}, …]"]
    form -->|"1"| val
    val -->|"2 fine"| ok
    val -.->|"2 not fine"| bad
    cat["📚 openapi.yaml — the catalogue<br/>paths · params · schemas · errors"]
    cat -.->|"3 describes all of it"| form

❓ What

JSON: objects {}, arrays [], strings, numbers, booleans, null. No comments, no trailing commas, no dates (they are strings — agree on ISO 8601). Content-Type: application/json on both sides.
Validation happens at the counter, not in the archive: required fields, types, allowed values (enum), ranges, formats. Refuse with 400 and a problems list; never let a half-valid form reach storage.
Schema: the written shape of a form. In OpenAPI it is JSON Schema: type, required, enum, minLength, default.
OpenAPI (api/openapi.yaml): paths → operations → parameters, requestBody, responses; components/schemas for the shared forms (Student, StudentInput, Error). One file describes the whole counter; lesson 12 uses it for docs and tests.
Output is a form too: clients depend on field names and types you return. Adding a field is safe; removing or renaming one is not (lesson 09).

🤔 Why

Because the archive is the expensive part. A form checked at the counter costs microseconds; a bad row written to the database costs a data clean-up, and a 500 where a 400 belonged costs an on-call engineer an hour. The catalogue is the other half: an API without a written contract is a rumour.

🔧 How (in this repo)

validate_student(body) in school_api.py returns a list of {field, problem} dicts; do_POST and do_PUT refuse with 400 validation_failed when the list is not empty. Compare it, line by line, with StudentInput in api/openapi.yaml — they must always agree.

🧪 Try it

K='X-API-Key: hall-pass-123'; B=http://127.0.0.1:8080/v1; J='Content-Type: application/json'
curl -s -X POST $B/students -H "$K" -H "$J" -d '{"name":"","class":"9Z"}'        # 400 with two problems
curl -s -X POST $B/students -H "$K" -H "$J" -d '{"name":"Zoya","class":"3B"}'    # 201; grade defaults to C
curl -s -X POST $B/students -H "$K" -H "$J" -d '{"name":"Zoya","class":"3B","grade":"Z"}'   # 400: grade
# now change the contract: add a required "roll_no" field to validate_student() AND openapi.yaml, restart, retest

✅ Verify — what you should see

The first call returns 400 with problems naming name and class; the second returns 201 and a body with "grade": "C"; the third names grade. After your roll_no change, the second call fails until you add the field — and the catalogue says why.

🏁 What you just proved

The counter refuses bad forms with a field-level reason before any work is done, and the catalogue and the code describe the same form.

⚠️ Common mistakes

validating in the database instead of at the counter — a constraint error becomes a 500
one error message for every problem ("invalid input") — say which field and why
a catalogue that drifts from the code — generate one from the other, or test them against each other (lesson 12)
sending dates as new Date() strings — agree on ISO 8601 and time zones

🏭 Why this matters in production: contract-first teams generate client SDKs, mocks and tests from the OpenAPI file, so frontend and backend build in parallel. Contract-less teams discover field names in Slack.

⏭️ Next

Time to open the counter and read every line: build an API — the four parts of school_api.py.

git checkout lesson-05-build-an-api

← Previousrest resources Next →build an api

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