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

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

📨 धडा 02 — HTTP ची रचना: चिठ्ठी आणि शिक्का

📍 तुम्ही इथे आहात: 12 पैकी धडा 02 · मागे: lesson-01-why-apis · पुढे: lesson-03-rest-resources

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

धडा 01, आणि त्यासोबत request आणि response ची नेमकी रचना — प्रत्येक slip वरच्या पाच गोष्टी आणि प्रत्येक शिक्का मारलेल्या उत्तरावरच्या तीन गोष्टी.

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

Counter वरच्या प्रत्येक slip वर तेच रकाने असतात, नेहमी त्याच क्रमाने:

काय करायचे — method: GET (वाचा), POST (जोडा), PUT (पूर्ण बदला), DELETE (काढा).
कशाबद्दल — path: /v1/students/2.
समासातल्या जादा नोंदी — headers: "मला JSON समजते" (Accept), "हा माझा pass" (X-API-Key), "बदलले असेल तरच" (If-None-Match).
प्रत्यक्ष form — body: फक्त तुम्ही काही जोडत किंवा बदलत असाल तेव्हा ({"name": "Zoya", "class": "3B"}).
शेवटी एक query — ?limit=2&class=3A: filters आणि पर्याय.

Clerk च्या उत्तराचे तीन भाग असतात: शिक्का (status code), काही समासातल्या नोंदी (ETag, Content-Type, Location सारखे headers), आणि मजकूर (body, बहुतेक वेळा JSON). शिक्के कुटुंबांत येतात:

2xx — झाले. 200 OK, 201 Created (ते इथे राहते: Location), 204 No Content (झाले, सांगण्यासारखे काही नाही).
3xx — त्याऐवजी तिकडे जा. 304 Not Modified (तुमची प्रत अजून चांगली आहे).
4xx — तुमची slip चुकीची आहे. 400 चुकीचा form, 401 pass नाही, 403 चुकीचा pass, 404 असे काही नाही, 409 संघर्ष (conflict), 415 चुकीचा कागद, 429 खूप जास्त slips.
5xx — आमचे office बिघडले आहे. 500, 502, 503, 504 — तुमची चूक नाही; नंतर पुन्हा प्रयत्न करा.

🗺️ आकृती

sequenceDiagram
    participant C as 🧑 client
    participant S as 🏢 school-api
    C->>S: 1 GET /v1/students/2  (Accept: application/json)
    S-->>C: 2 200 OK · ETag "0e9a…" · Cache-Control · {"id":2,"name":"Katrina",…}
    C->>S: 3 GET /v1/students/99
    S-->>C: 4 404 Not Found · {"error":{"code":"not_found","message":"No student with id 99."}}
    Note over C,S: 2xx done · 3xx elsewhere · 4xx your slip · 5xx our office

❓ काय

Request म्हणजे text: एक request line (GET /v1/students/2 HTTP/1.1), headers (प्रत्येक ओळीत एक), एक रिकामी ओळ, मग body. curl -v तुम्हाला नेमके हेच दाखवतो.
Response सुद्धा text आहे: एक status line (HTTP/1.0 200 OK), headers, रिकामी ओळ, body. curl -i body सोबत headers छापतो.
Headers म्हणजे दोन्ही बाजू वाटाघाटीसाठी वापरतात त्या समासातल्या नोंदी: format (Content-Type, Accept), ओळख (Authorization, X-API-Key), caching (ETag, Cache-Control), tracing (X-Request-Id).
Content-Type: application/json हे body बद्दलचे वचन आहे. आमचे API JSON नसलेली body 415 ने नाकारते — पाहा school_api.py मधले read_json().
Status codes म्हणजे शब्दसंग्रह आहे, सजावट नाही: clients त्यानुसार निर्णय घेतात (503 retry करा, 400 कधीच retry करू नका — धडा 07).

🔧 सातही शिक्के, चित्रात: GET, HEAD, OPTIONS, POST, PUT, PATCH आणि DELETE — safe, idempotent, cacheable, प्रत्येक देत असलेले status codes, आणि प्रत्येक नियम या counter वर सिद्ध करणारी script — हे सगळे धडा 13 — प्रत्येक REST method मध्ये आहे. bash api/methods_demo.sh ते चालवते (HEAD आणि OPTIONS सुद्धा उत्तर देतात: curl -I आणि curl -X OPTIONS -i करून पाहा).

🤔 का

कारण या क्षेत्रातले प्रत्येक साधन — curl, browsers, load balancers, caches, AWS API Gateway, तुमचा framework — हीच नेमकी रचना समजते. ती अस्खलित बोलता आली की तुम्ही curl -v ने आणि docs शिवाय कोणतेही API debug करू शकता: method आणि path सांगतात तुम्ही काय मागितले, status सांगतो चूक कोणाची आहे, headers सांगतात पुढे काय करायचे.

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

school_api.py मधले send(status, body, headers) प्रत्येक शिक्का लिहिते: status line, X-API-Version, X-Request-Id, Content-Type, body. error(status, code, message) प्रत्येक नकार एकाच आकारात लिहिते — हे इतके महत्त्वाचे का आहे ते धडा 07 सांगतो.

🧪 करून पाहा

python3 api/school_api.py                          # terminal 1
curl -v http://127.0.0.1:8080/v1/students/2        # terminal 2 — read the > and < lines
curl -i http://127.0.0.1:8080/v1/students/99       # the 404 stamp + the error body
curl -i -X POST http://127.0.0.1:8080/v1/students -d 'not json'   # 415: wrong paper

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

curl -v तुमच्या request च्या ओळी > ने सुरू झालेल्या (method, path, Host, Accept) आणि उत्तर < ने सुरू झालेले (HTTP/1.0 200 OK, ETag, Cache-Control, Content-Type) दाखवतो. 404 ला error.code = not_found असलेली JSON body असते. -d 'not json' call auth तपासण्याच्या आधीच 415 unsupported_media_type ने नाकारला जातो.

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

तुम्ही request आणि response text म्हणून वाचू शकता, आणि प्रत्येक उत्तर चार शिक्का-कुटुंबांपैकी कोणत्या कुटुंबातले आहे ते तुम्हाला कळते — API debugging चा 80 % भाग हाच आहे.

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

फक्त body वाचणे — अर्धा अर्थ status code आणि headers मध्ये असतो
Content-Type: application/json शिवाय JSON पाठवणे — अनेक servers, आमच्यासकट, ते नाकारतात (415)
4xx आणि 5xx सारखेच मानणे — एकाचा अर्थ तुमची slip दुरुस्त करा, दुसऱ्याचा अर्थ थांबा आणि retry करा

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: load balancers 5xx मोजतात, caches Cache-Control पाळतात, alerting प्रत्येक status कुटुंबाच्या error दरावर वाजते. आत {"ok": false} ठेवून 200 परत करणारे API या प्रत्येक साधनाला दिसतच नाही.

⏭️ पुढे

Slips वरच्या गोष्टींना नावे कशी द्यायची? फाइलिंग कपाटांतली नामे — REST resources आणि पुन्हा करायला सुरक्षित असलेली क्रियापदे.

git checkout lesson-03-rest-resources

📨 Lesson 02 — HTTP anatomy: the slip and the stamp

📍 You are here: Lesson 02 of 12 · Previous: lesson-01-why-apis · Next: lesson-03-rest-resources

📦 What's in this branch

Lesson 01, plus the exact layout of a request and a response — the five things on every slip and the three things on every stamped answer.

🧒 Explain like I'm 5

Every slip at the counter has the same boxes, always in the same order:

What to do — the method: GET (read), POST (add), PUT (replace), DELETE (remove).
About what — the path: /v1/students/2.
Extra notes in the margin — headers: "I speak JSON" (Accept), "here is my pass" (X-API-Key), "only if it changed" (If-None-Match).
The form itself — the body: only when you are adding or replacing something ({"name": "Zoya", "class": "3B"}).
A query at the end — ?limit=2&class=3A: filters and options.

The clerk's answer has three parts: the stamp (a status code), some margin notes (headers such as ETag, Content-Type, Location), and the contents (the body, usually JSON). Stamps come in families:

2xx — done. 200 OK, 201 Created (here is where it lives: Location), 204 No Content (done, nothing to say).
3xx — go there instead. 304 Not Modified (your copy is still good).
4xx — YOUR slip is wrong. 400 bad form, 401 no pass, 403 wrong pass, 404 no such thing, 409 conflict, 415 wrong paper, 429 too many slips.
5xx — OUR office is broken. 500, 502, 503, 504 — not your fault; try again later.

🗺️ Diagram

sequenceDiagram
    participant C as 🧑 client
    participant S as 🏢 school-api
    C->>S: 1 GET /v1/students/2  (Accept: application/json)
    S-->>C: 2 200 OK · ETag "0e9a…" · Cache-Control · {"id":2,"name":"Katrina",…}
    C->>S: 3 GET /v1/students/99
    S-->>C: 4 404 Not Found · {"error":{"code":"not_found","message":"No student with id 99."}}
    Note over C,S: 2xx done · 3xx elsewhere · 4xx your slip · 5xx our office

❓ What

A request is text: a request line (GET /v1/students/2 HTTP/1.1), headers (one per line), a blank line, then the body. curl -v shows you exactly this.
A response is text too: a status line (HTTP/1.0 200 OK), headers, blank line, body. curl -i prints the headers with the body.
Headers are the margin notes both sides use to negotiate: format (Content-Type, Accept), identity (Authorization, X-API-Key), caching (ETag, Cache-Control), tracing (X-Request-Id).
Content-Type: application/json is a promise about the body. Our API refuses a body that is not JSON with 415 — check read_json() in school_api.py.
Status codes are a vocabulary, not decoration: clients branch on them (retry a 503, never retry a 400 — lesson 07).

🔧 All seven stamps, drawn: GET, HEAD, OPTIONS, POST, PUT, PATCH and DELETE — safe, idempotent, cacheable, the status codes each returns, and a script that proves every rule against this counter — are lesson 13 — every REST method. bash api/methods_demo.sh runs it (HEAD and OPTIONS answer too: try curl -I and curl -X OPTIONS -i).

🤔 Why

Because every tool in the trade — curl, browsers, load balancers, caches, the AWS API Gateway, your framework — understands this exact layout. Speak it fluently and you can debug any API with curl -v and no docs: the method and path say what you asked, the status says whose fault it is, the headers say what to do next.

🔧 How (in this repo)

send(status, body, headers) in school_api.py writes every stamp: the status line, X-API-Version, X-Request-Id, Content-Type, the body. error(status, code, message) writes every refusal in one shape — lesson 07 explains why that matters so much.

🧪 Try it

python3 api/school_api.py                          # terminal 1
curl -v http://127.0.0.1:8080/v1/students/2        # terminal 2 — read the > and < lines
curl -i http://127.0.0.1:8080/v1/students/99       # the 404 stamp + the error body
curl -i -X POST http://127.0.0.1:8080/v1/students -d 'not json'   # 415: wrong paper

✅ Verify — what you should see

curl -v shows your request lines prefixed > (method, path, Host, Accept) and the answer prefixed < (HTTP/1.0 200 OK, ETag, Cache-Control, Content-Type). The 404 has a JSON body with error.code = not_found. The -d 'not json' call is refused with 415 unsupported_media_type before auth is even checked.

🏁 What you just proved

You can read a request and a response as text, and you know which of the four stamp families each answer belongs to — that is 80 % of API debugging.

⚠️ Common mistakes

reading only the body — the status code and headers carry half the meaning
sending JSON without Content-Type: application/json — many servers, ours included, refuse it (415)
treating 4xx and 5xx the same — one means fix your slip, the other means wait and retry

🏭 Why this matters in production: load balancers count 5xx, caches obey Cache-Control, alerting fires on error rates per status family. An API that returns 200 with {"ok": false} inside is invisible to every one of those tools.

⏭️ Next

How do we name the things on the slips? Nouns in filing cabinets — REST resources and the verbs that are safe to repeat.

git checkout lesson-03-rest-resources

← Previouswhy apis Next →rest resources

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