🔢 धडा 09 — Versioning: जुने फॉर्म न फेकता नवे फॉर्म

📍 तुम्ही इथे आहात: 12 पैकी धडा 09 · मागे: lesson-08-pagination-filtering · पुढे: lesson-10-rate-limits-caching

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

धडे 01–08, आणि त्यासोबत आधीपासून forms भरणाऱ्या apps ना न मोडता counter कसा विकसित होतो: additive बदल, मोडणारे बदल (breaking changes), /v1 → /v2, आणि एखादा form निवृत्त करण्याची सभ्य पद्धत.

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

वीस apps रोज विद्यार्थ्याचा form भरतात. एका सकाळी office ला बदल हवा असतो. बदल दोन प्रकारचे असतात:

रकाना जोडणे ➕ — नवीन ऐच्छिक field (house), नवीन endpoint (/v1/homework), कोणावरही सक्ती नसलेली नवीन किंमत. जुने apps चालूच राहतात: त्यांना माहीत नसलेल्या रकान्यांकडे ते दुर्लक्ष करतात. सुरक्षित. तेच version.
रकाना बदलणे किंवा काढणे 💥 — class चे नाव section करणे, grade ला आकडा बनवणे, एखादे app ज्यावर अवलंबून आहे ते field काढणे. बदल ship होताक्षणी जुने apps मोडतात. सुरक्षित नाही. नवीन version.

म्हणून office नवीन form /v2 म्हणून छापते आणि काही काळ /v1 सुद्धा देत राहते. ते निवृत्तीची सभ्यपणे घोषणा करते: प्रत्येक v1 उत्तरावर Deprecation सूचना, एक Sunset तारीख, एक migration मार्गदर्शक, आणि ते counter वर लक्ष ठेवते — v1 तेव्हाच काढले जाते जेव्हा आणखी v1 slips येणे बंद होते.

🗺️ आकृती

flowchart LR
    v1["🔢 /v1/students<br/>{id, name, class, grade}"]
    add["➕ additive: + house, + /homework<br/>same version, old apps fine"]
    brk["💥 breaking: class → section,<br/>grade → number"]
    v2["/v2/students<br/>new form, side by side"]
    sunset["🗓️ Deprecation + Sunset headers on v1<br/>metrics per version → remove v1 when quiet"]
    v1 -->|"1 safe"| add
    v1 -->|"2 not safe"| brk --> v2
    v2 -.->|"3"| sunset

❓ काय

Additive (न मोडणारे): नवीन ऐच्छिक request fields, नवीन response fields, नवीन endpoints, नवीन enum किमती जर clients ना अनोळखी किमतींकडे दुर्लक्ष करायला सांगितले असेल तर. Validation चा नियम सैल करणे सहसा सुरक्षित असते; तो कडक करणे मोडणारे असते.
मोडणारे (breaking): field चे नाव बदलणे/काढणे, type किंवा अर्थ बदलणे, status code बदलणे, error चे codes बदलणे, auth च्या अटी बदलणे, cursor चा अर्थ बदलणे.
Version कुठे राहते: path मध्ये (/v1/, दिसणारे, route करता येणारे, cache करता येणारे — आमचे), किंवा header मध्ये (Accept: application/vnd.school.v2+json, स्वच्छ URLs, logs मध्ये अदृश्य). दोन्ही चालतात; एक निवडा आणि कधीच मिसळू नका.
Deprecation (Deprecation: true, Sunset: <date>, Link: <migration guide>) headers मुळे clients ते program द्वारे ओळखू शकतात; प्रत्येक version च्या वापराचे metrics सांगतात की ते काढणे कधी सुरक्षित आहे.
दोन्ही बाजूंना मजबूतपणा: servers अनोळखी request fields कडे दुर्लक्ष करतात (किंवा ते सातत्याने नाकारतात); clients अनोळखी response fields कडे दुर्लक्ष करतात. ही एकच सवय बहुतेक बदल additive बनवते.

🤔 का

कारण API म्हणजे अशा code ला दिलेले वचन जो तुम्ही पाहू किंवा update करू शकत नाही. Version शिवायचा मोडणारा बदल म्हणजे प्रत्येक वापरकर्त्यावर एकत्र कोसळणारे outage — नेमकी तीच गोष्ट टाळण्यासाठी counter अस्तित्वात आला (धडा 01). Versioning म्हणजे नोकरशाही नाही; पुढे जात असतानाही office आपला शब्द कसा पाळते ते हे आहे.

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

प्रत्येक path /v1/ ने सुरू होतो (school_api.py मधले VERSION) आणि प्रत्येक response वर X-API-Version: v1 असते. STUDENTS मध्ये आणि openapi.yaml मधल्या Student मध्ये field जोडणे additive आहे; class चे नाव बदलणे हे तुमचे पहिले /v2 ठरेल.

🧪 करून पाहा

# 1) additive: add "house": "red" to every student in STUDENTS and to the Student schema. Restart.
curl -s http://127.0.0.1:8080/v1/students/2            # old clients still parse this — they ignore "house"
# 2) breaking, done right — on paper (5 minutes):
#    write the /v2 form with "section" instead of "class", the Deprecation + Sunset headers you would add to v1,
#    and the one-paragraph migration note. Then decide the date you would remove v1 — and what metric tells you it is safe.
# 3) look at the version stamp:
curl -si http://127.0.0.1:8080/v1/health | grep -i x-api-version

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

पायरी 1 नंतर smoke test अजूनही सुरुवातीपासून शेवटपर्यंत pass होतो (तो तपासत असलेल्या कशाचेही नाव बदलले नाही) आणि प्रत्येक विद्यार्थ्यात house दिसते. पायरी 3 प्रत्येक उत्तरावर X-API-Version: v1 छापते. तुमच्या पायरी-2 च्या टिपणात एक field, एक header, एक तारीख आणि एक metric असते.

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

तुम्ही additive बदल आणि मोडणारा बदल यांतला फरक ओळखू शकता, पहिला त्याच version वर ship करू शकता, आणि दुसऱ्याचे नियोजन कोणालाही न मोडता करू शकता.

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

"आपण फक्त नाव बदलू, सगळे update करतील" — तुमच्या वेळापत्रकानुसार कोणीच update करत नाही
प्रत्येक endpoint किंवा प्रत्येक field नुसार versioning — संपूर्ण counter साठी एकच version
metrics शिवाय /v1 कायम ठेवणे — जे मोजता येत नाही ते तुम्ही निवृत्त करू शकत नाही
एकाच वेळी सगळे बदलणारे /v2 — मोठे rewrites अडकतात; छोटे मोडणारे बदल ship होतात
अनोळखी fields वर fail होणारे clients — ते प्रत्येक additive बदलाला मोडणारा बदल बनवतात

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: लोकांना आवडणारे APIs (Stripe, GitHub) प्रकाशित sunset तारखांसह वर्षानुवर्षे जुने versions चालवत आले आहेत. लोक ज्यांना सोडून जातात त्यांनी एखाद्या मंगळवारी एक field मोडलेले असते.

⏭️ पुढे

भाराखालचा counter: rate limits, caching, timeouts आणि backoff — रांग, प्रत, आणि सभ्य client.

git checkout lesson-10-rate-limits-caching

🔢 Lesson 09 — Versioning: new forms without throwing the old ones away

📍 You are here: Lesson 09 of 12 · Previous: lesson-08-pagination-filtering · Next: lesson-10-rate-limits-caching

📦 What's in this branch

Lessons 01–08, plus how a counter evolves without breaking the apps that already fill in its forms: additive changes, breaking changes, /v1 → /v2, and the polite way to retire a form.

🧒 Explain like I'm 5

Twenty apps fill in the student form every day. One morning the office wants a change. There are two kinds:

Adding a box ➕ — a new optional field (house), a new endpoint (/v1/homework), a new value nobody is forced to use. Old apps keep working: they ignore boxes they do not know. Safe. Same version.
Changing or removing a box 💥 — renaming class to section, making grade a number, deleting a field an app relies on. Old apps break the moment it ships. Not safe. New version.

So the office prints the new form as /v2 and keeps handing out /v1 for a while. It announces the retirement politely: a Deprecation note on every v1 answer, a Sunset date, a migration guide, and it watches the counter — v1 is removed only when no more v1 slips arrive.

🗺️ Diagram

flowchart LR
    v1["🔢 /v1/students<br/>{id, name, class, grade}"]
    add["➕ additive: + house, + /homework<br/>same version, old apps fine"]
    brk["💥 breaking: class → section,<br/>grade → number"]
    v2["/v2/students<br/>new form, side by side"]
    sunset["🗓️ Deprecation + Sunset headers on v1<br/>metrics per version → remove v1 when quiet"]
    v1 -->|"1 safe"| add
    v1 -->|"2 not safe"| brk --> v2
    v2 -.->|"3"| sunset

❓ What

Additive (non-breaking): new optional request fields, new response fields, new endpoints, new enum values if clients were told to ignore unknown ones. Relaxing a validation rule is usually safe; tightening one is breaking.
Breaking: rename/remove a field, change a type or meaning, change a status code, change the error codes, change auth requirements, change cursor semantics.
Where the version lives: the path (/v1/, visible, routable, cacheable — ours), or a header (Accept: application/vnd.school.v2+json, cleaner URLs, invisible in logs). Both work; pick one and never mix.
Deprecation (Deprecation: true, Sunset: <date>, Link: <migration guide>) headers let clients detect it programmatically; usage metrics per version tell you when it is safe to remove.
Robustness on both sides: servers ignore unknown request fields (or reject them consistently); clients ignore unknown response fields. That single habit makes most changes additive.

🤔 Why

Because an API is a promise to code you cannot see or update. A breaking change without a version is a coordinated outage across every consumer — the very thing the counter existed to prevent (lesson 01). Versioning is not bureaucracy; it is how the office keeps its word while still moving.

🔧 How (in this repo)

Every path starts with /v1/ (VERSION in school_api.py) and every response carries X-API-Version: v1. Adding a field to STUDENTS and Student in openapi.yaml is additive; renaming class would be your first /v2.

🧪 Try it

# 1) additive: add "house": "red" to every student in STUDENTS and to the Student schema. Restart.
curl -s http://127.0.0.1:8080/v1/students/2            # old clients still parse this — they ignore "house"
# 2) breaking, done right — on paper (5 minutes):
#    write the /v2 form with "section" instead of "class", the Deprecation + Sunset headers you would add to v1,
#    and the one-paragraph migration note. Then decide the date you would remove v1 — and what metric tells you it is safe.
# 3) look at the version stamp:
curl -si http://127.0.0.1:8080/v1/health | grep -i x-api-version

✅ Verify — what you should see

After step 1 the smoke test still passes end to end (nothing it checks was renamed) and house appears in every student. Step 3 prints X-API-Version: v1 on every answer. Your step-2 note names a field, a header, a date and a metric.

🏁 What you just proved

You can tell an additive change from a breaking one, ship the first on the same version, and plan the second without breaking anyone.

⚠️ Common mistakes

"we'll just rename it, everyone will update" — nobody updates on your schedule
versioning per endpoint or per field — one version for the whole counter
keeping /v1 forever with no metrics — you cannot retire what you cannot measure
a /v2 that changes everything at once — big rewrites stall; small breaking changes ship
clients that fail on unknown fields — they turn every additive change into a breaking one

🏭 Why this matters in production: the APIs people love (Stripe, GitHub) have run old versions for years with published sunset dates. The ones people leave broke a field on a Tuesday.

⏭️ Next

The counter under load: rate limits, caching, timeouts and backoff — the queue, the copy, and the polite client.

git checkout lesson-10-rate-limits-caching

← Previouspagination filtering Next →rate limits caching

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