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

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

🚪 धडा 12 — Testing, docs आणि gateway: शाळेचे गेट

📍 तुम्ही इथे आहात: 12 पैकी धडा 12 — शेवटचा धडा! · मागील: lesson-11-beyond-rest

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

पूर्ण कोर्स, आणि त्यासोबत शेवटचा टप्पा: CI मध्ये चालणाऱ्या contract tests, कॅटलॉगमधून तयार होणारे documentation, observability (request ids आणि log lines), आणि API gateway — प्रत्येक काउंटरसमोरचे शाळेचे गेट.

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

काउंटर लोकांसाठी उघडण्याआधी तीन गोष्टी घडतात:

तपासणीस 🧪 — कोणीतरी मुद्दाम प्रत्येक प्रकारची slip देतो आणि प्रत्येक शिक्का कॅटलॉगशी जुळवून पाहतो. तेच म्हणजे api/openapi.yaml शी तुलना केलेला api/smoke_test.sh: एक contract test. प्रत्येक बदलावर तो चालवा (CI/CD शाळेचे तपासणी टेबल).
छापलेली मार्गदर्शिका 📚 — कॅटलॉगच docs page, client library आणि mock server बनतो. मार्गदर्शिका कोणीही हाताने लिहीत नाही.
गेट 🚪 — काउंटरसमोर शाळेचे गेट उभे असते (एक API gateway): ते passes तपासते, रांग सांभाळते, प्रत्येक slip योग्य काउंटरकडे पाठवते, आणि log लिहिते. त्यामागचा काउंटर छोटाच राहतो. AWS शाळा हे गेट API Gateway (L25) म्हणून भाड्याने घेते; Kubernetes शाळेचे Ingress (L10) हीच कल्पना आहे.

आणि प्रत्येक slip मागे खूण राहते: उत्तरावर एक X-Request-Id आणि काउंटरवर एक log line — त्यामुळे "14:03 ला माझ्या slip चे काय झाले?" हे गूढ नव्हे, फक्त एक grep ठरते.

🗺️ आकृती

flowchart LR
    ci["🧪 CI: smoke_test.sh vs openapi.yaml<br/>every slip, every stamp"]
    docs["📚 docs, clients, mocks<br/>generated from the catalogue"]
    gate["🚪 API gateway<br/>auth · rate limit · routing · TLS · logs"]
    api["🏢 school-api<br/>small, focused"]
    obs["👀 X-Request-Id + one log line per slip<br/>latency, error rate per route"]
    ci -->|"1 green?"| docs -->|"2 publish"| gate -->|"3 route"| api
    api -.->|"4"| obs

❓ काय

Contract test: कॅटलॉगमधल्या प्रत्येक operation साठी किमान एक request आणि status + body shape वर एक assertion. आमचा smoke test हे माणसाला वाचता येणारे रूप आहे; tools OpenAPI मधून हेच तयार करू शकतात.
OpenAPI मधून docs: renderers (Swagger UI, Redoc), तयार होणारे SDKs, frontend टीम्ससाठी mock servers. कॅटलॉग हा एकमेव स्रोत आहे.
काउंटरवर observability: प्रत्येक slip साठी एक request id (gateway कडून आलेला स्वीकारा किंवा नवा तयार करा), एक structured log line (method, path, status, ms, id), प्रत्येक route साठी latency percentiles आणि error rate, आणि 5xx rate व p95 वर alerts.
API gateway: auth (keys, JWT validation, OAuth), rate limits, routing/versions, TLS termination, WAF, request logs — एका ठिकाणी. Managed: AWS API Gateway; स्वतः चालवायचे: Kong, Envoy, NGINX, plugins असलेले Kubernetes Ingress.
API मध्येच काय राहते: validation, व्यवसायाचे नियम, error shape, idempotency. गेट धोरण लागू करते; काउंटर अर्थ लागू करतो.

🧪 Testing चा संपूर्ण नकाशा: हा धडा smoke test आणि contract test बांधतो. इतर सात प्रकार — functional, integration, regression, load, stress, security, fuzz — आणि UI प्रकार एका ओळीत एक असे काढले आहेत धडा 16 — API test चा प्रत्येक प्रकार मध्ये, प्रत्येकासोबत तो या काउंटरवर कसा चालवायचा ते.

🤔 का

कारण tests नसलेला काउंटर गुपचूप बिघडतो, docs नसलेला काउंटर चुकीच्या पद्धतीने बोलावला जातो, request id नसलेल्या काउंटरचा debug होत नाही, आणि पाच काउंटर्सनी प्रत्येकी auth आणि rate limits पुन्हा लिहिणे म्हणजे bugs चे पाच संच. गेट आणि कॅटलॉग यांच्या मदतीनेच एक छोटी टीम अनेक काउंटर्स सुरक्षितपणे चालवते.

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

send() X-Request-Id तयार करतो आणि log_line() खूण छापतो; api/smoke_test.sh हा contract test आहे; api/openapi.yaml हा कॅटलॉग आहे. Gateway या repo मध्ये नाही — तो तुम्ही भाड्याने घेता किंवा समोर चालवता तो भाग आहे (AWS L25, Kubernetes L10).

🧪 करून पाहा — शेवटचा प्रकल्प

# 1) make the smoke test a real check: exit non-zero when a stamp is wrong
#    (wrap each curl with an expected status; e.g. code=$(curl -s -o /dev/null -w '%{http_code}' …); [ "$code" = 201 ] || exit 1)
# 2) follow one slip end to end:
curl -si http://127.0.0.1:8080/v1/students/2 | grep -i x-request-id          # copy the id
#    …and find that id in terminal 1's log line: GET /v1/students/2 → 200 · 1 ms · <id>
# 3) render the catalogue: paste api/openapi.yaml into https://editor.swagger.io — every form, documented, for free
# 4) on paper: which of these does the gate do, which does the counter do?
#    check the API key · reject class "9Z" · 429 after 20 slips · add X-Request-Id · replay an Idempotency-Key · TLS

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

तुमचा पक्का केलेला smoke test निरोगी API वर 0 ने संपतो आणि तुम्ही मुद्दाम एखादा status code बिघडवल्यावर 1 ने (do_POST मध्ये 201 चे 200 करा आणि तो fail होताना पाहा). तुम्ही copy केलेला request id server log मध्ये दिसतो. Render केलेला कॅटलॉग कोर्समधला प्रत्येक path त्याच्या schemas सह दाखवतो. तुमचे कागदावरचे उत्तर: गेट = key, 429, request id, TLS; काउंटर = validation, idempotency replay.

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

काउंटर testable, documented, traceable आहे आणि गेटमागे उभा राहायला तयार आहे — API उघड करणे सुरक्षित बनवणाऱ्या या चार गोष्टी.

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

फक्त 200 तपासणाऱ्या tests — error शिक्केही तपासा; ते contract चा अर्धा भाग आहेत
code पासून दूर जाणारे हाताने लिहिलेले docs — कॅटलॉगमधून तयार करा
gateway मध्ये व्यवसायाचे नियम — गेट धोरण लागू करते, काउंटर अर्थ लागू करतो
request id नसलेले logs — प्रत्येक incident पुरातत्त्व संशोधन बनते
5xx rate वर alert नाही — outages बद्दल तुम्हाला ग्राहकांकडून कळते

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: API public होण्याआधी reviewers हीच यादी वापरतात: CI मध्ये contract tests, तयार होणारे docs, request ids आणि प्रत्येक route चे metrics, समोर एक gateway. एक जरी सुटले तरी तेच incident बनते.

🎓 काउंटर आता तुमचा आहे

दप्तरखाना → काउंटर → slip आणि शिक्का → कपाटांतली नामे → ठरलेला form → चार भाग → हॉल पास → पावती नंबर → "पुढचे 20" → जुन्या forms शेजारी नवे forms → रांग आणि प्रत → callback → गेट. तुम्ही फक्त APIs शिकला नाहीत — तुम्ही एक चालवता. 🏢🎓

शाळेतले पुढचे दरवाजे: Database शाळा या काउंटरमागची नोंदींची खोली टिकाऊ बनवते; UI शाळा या slips भरणारा सूचना फलक बांधते.

git checkout main
bash api/smoke_test.sh     # one last run, for fun

🚪 Lesson 12 — Testing, docs & the gateway: the school gate

📍 You are here: Lesson 12 of 12 — the final lesson! · Previous: lesson-11-beyond-rest

📦 What's in this branch

The complete course, plus the last mile: contract tests that run in CI, documentation generated from the catalogue, observability (request ids and log lines), and the API gateway — the school gate in front of every counter.

🧒 Explain like I'm 5

Three things happen before a counter opens to the public:

The inspector 🧪 — someone hands in every kind of slip on purpose and checks every stamp against the catalogue. That is api/smoke_test.sh compared with api/openapi.yaml: a contract test. Run it on every change (the CI/CD school's checking desk).
The printed guide 📚 — the catalogue becomes the docs page, the client library and the mock server. Nobody writes the guide by hand.
The gate 🚪 — in front of the counter stands the school gate (an API gateway): it checks passes, keeps the queue, routes each slip to the right counter, and writes the log. The counter behind it stays small. The AWS school rents this gate as API Gateway (L25); the Kubernetes school's Ingress (L10) is the same idea.

And every slip leaves a trace: an X-Request-Id on the answer and one log line at the counter — so "what happened to my slip at 14:03?" is a grep, not a mystery.

🗺️ Diagram

flowchart LR
    ci["🧪 CI: smoke_test.sh vs openapi.yaml<br/>every slip, every stamp"]
    docs["📚 docs, clients, mocks<br/>generated from the catalogue"]
    gate["🚪 API gateway<br/>auth · rate limit · routing · TLS · logs"]
    api["🏢 school-api<br/>small, focused"]
    obs["👀 X-Request-Id + one log line per slip<br/>latency, error rate per route"]
    ci -->|"1 green?"| docs -->|"2 publish"| gate -->|"3 route"| api
    api -.->|"4"| obs

❓ What

Contract test: for each operation in the catalogue, at least one request and an assertion on status + body shape. Our smoke test is the human-readable version; tools can generate the same from OpenAPI.
Docs from OpenAPI: renderers (Swagger UI, Redoc), generated SDKs, mock servers for frontend teams. The catalogue is the single source.
Observability at the counter: a request id per slip (accept one from the gateway or mint one), a structured log line (method, path, status, ms, id), latency percentiles and error rate per route, and alerts on the 5xx rate and p95.
API gateway: auth (keys, JWT validation, OAuth), rate limits, routing/versions, TLS termination, WAF, request logs — centralised. Managed: AWS API Gateway; self-hosted: Kong, Envoy, NGINX, a Kubernetes Ingress with plugins.
What stays in the API: validation, business rules, the error shape, idempotency. Gates enforce policy; counters enforce meaning.

🧪 The full testing map: this lesson builds the smoke test and the contract test. The other seven kinds — functional, integration, regression, load, stress, security, fuzz — and the UI kind are drawn one per row in lesson 16 — every kind of API test, each with how you would run it against this counter.

🤔 Why

Because a counter without tests breaks silently, a counter without docs gets called wrongly, a counter without a request id is undebuggable, and five counters each re-implementing auth and rate limits is five sets of bugs. The gate and the catalogue are how one small team runs many counters safely.

🔧 How (in this repo)

send() mints X-Request-Id and log_line() prints the trace; api/smoke_test.sh is the contract test; api/openapi.yaml is the catalogue. The gateway is not in the repo — it is the piece you rent or run in front (AWS L25, Kubernetes L10).

🧪 Try it — the capstone

# 1) make the smoke test a real check: exit non-zero when a stamp is wrong
#    (wrap each curl with an expected status; e.g. code=$(curl -s -o /dev/null -w '%{http_code}' …); [ "$code" = 201 ] || exit 1)
# 2) follow one slip end to end:
curl -si http://127.0.0.1:8080/v1/students/2 | grep -i x-request-id          # copy the id
#    …and find that id in terminal 1's log line: GET /v1/students/2 → 200 · 1 ms · <id>
# 3) render the catalogue: paste api/openapi.yaml into https://editor.swagger.io — every form, documented, for free
# 4) on paper: which of these does the gate do, which does the counter do?
#    check the API key · reject class "9Z" · 429 after 20 slips · add X-Request-Id · replay an Idempotency-Key · TLS

✅ Verify — what you should see

Your hardened smoke test exits 0 on the healthy API and 1 after you deliberately break a status code (change 201 to 200 in do_POST and watch it fail). The request id you copied appears in the server log. The rendered catalogue shows every path from the course with its schemas. Your paper answer: gate = key, 429, request id, TLS; counter = validation, idempotency replay.

🏁 What you just proved

The counter is testable, documented, traceable and ready to stand behind a gate — the four things that make an API safe to expose.

⚠️ Common mistakes

tests that only check 200 — check the error stamps too; they are half the contract
hand-written docs that drift from the code — generate from the catalogue
business rules in the gateway — the gate enforces policy, the counter enforces meaning
logs without a request id — every incident becomes archaeology
no alert on the 5xx rate — you learn about outages from customers

🏭 Why this matters in production: this is the checklist reviewers use before an API goes public: contract tests in CI, generated docs, request ids and per-route metrics, a gateway in front. Miss one and it becomes the incident.

🎓 The counter is yours

The archive → the counter → the slip and the stamp → nouns in cabinets → the standard form → the four parts → the hall pass → receipt numbers → "the next 20" → new forms beside old → the queue and the copy → the callback → the gate. You didn't just learn APIs — you run one. 🏢🎓

Next doors in the school: the Database school makes the record room behind this counter durable; the UI school builds the notice board that fills in these slips.

git checkout main
bash api/smoke_test.sh     # one last run, for fun

← Previousbeyond rest Next →rest methods

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