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

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

📌 धडा 08 — Caching: सूचना फलक

📍 तुम्ही इथे आहात: 12 पैकी धडा 08 · मागे: lesson-07-throttling · पुढे: lesson-09-cors

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

धडे 01–07, आणि stage cache: TTL संपेपर्यंत office पुन्हा पुन्हा येणाऱ्या GET चे उत्तर आपल्या सूचना फलकावरून देते, आणि kitchen ला फक्त एकदाच विचारले जाते. तुम्हाला cache key काम करताना दिसेल आणि प्रत्येक user ची वेगळी उत्तरे एकच key कधीच का वाटून घेऊ नयेत ते कळेल. apigw/demo.py मधले cache() पाच मिनिटांत एकाच विद्यार्थिनीबद्दल चार वेळा विचारते.

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

अनेक पालक clerk ला तोच प्रश्न विचारतात: "ऐश्वर्या कोणत्या वर्गात आहे?" पहिल्या वेळी clerk kitchen पर्यंत चालत जाऊन विचारतो. मग clerk उत्तर सूचना फलकावर लावतो 📌, सोबत एक चिठ्ठी: "5 मिनिटांसाठी वैध".

पुढचा पालक विचारतो — clerk फलक वाचतो. Kitchen पर्यंत चालत जायची गरज नाही. 5 मिनिटांनंतर चिठ्ठी जुनी होते, म्हणून clerk ती काढून टाकतो आणि पुन्हा kitchen ला विचारतो.

फलक नेमक्या प्रश्नानुसार मांडलेला असतो. "ऐश्वर्याचा वर्ग" आणि "ऐश्वर्याचा वर्ग, मराठीत" या दोन वेगळ्या चिठ्ठ्या आहेत. आणि clerk ने "माझे गुण" कधीच फलकावर लावू नयेत — नाहीतर पुढचा पालक दुसऱ्याचे गुण वाचेल.

🗺️ आकृती

flowchart LR
    q0["+0 s GET /students/7"] -->|"Miss"| k["🍳 kitchen<br/>calls = 1"]
    k --> board["📌 notice board<br/>key: prod GET /students/7<br/>good until +300 s"]
    q1["+10 s"] -->|"Hit"| board
    q2["+210 s"] -->|"Hit"| board
    q3["+511 s — TTL passed"] -->|"Miss"| k2["🍳 kitchen<br/>calls = 2"]

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

❓ काय

Stage cache — फक्त REST APIs. तुम्ही ते प्रत्येक stage साठी चालू करता आणि आकार निवडता (0.5 GB पासून 237 GB पर्यंत). वापरले असो वा नसो, आकारानुसार तासाला bill होते — 0.5 GB साठी साधारण $0.02 प्रति तास, म्हणजे महिन्याला सुमारे $15 (अंदाजे; तुमचा Region तपासा).
TTL — उत्तर किती काळ टिकते: default 300 सेकंद, 0 ते 3600 पर्यंत. 0 म्हणजे caching बंद. तुम्ही ते प्रत्येक method साठी बदलू शकता.
Cache key — default नुसार method आणि resource path. कोणत्या query strings आणि headers सुद्धा key मध्ये जातील ते तुम्ही निवडता. Default नुसार फक्त GET cache होते.
Invalidation — संपूर्ण stage cache flush करा, किंवा ताजे उत्तर मिळवण्यासाठी client ला Cache-Control: max-age=0 पाठवू द्या. require authorization चालू करा, म्हणजे फक्त execute-api:InvalidateCache असलेले callers हे करू शकतील; नाहीतर कोणीही तुमचा cache निरुपयोगी करू शकतो.
Metrics — CacheHitCount आणि CacheMissCount (धडा 11).
HTTP APIs ना cache नसतो: समोर CloudFront ठेवा, किंवा application मध्ये cache करा.

🤔 का

कारण अनेक APIs तेच तेच पुन्हा पुन्हा वाचतात — वेळापत्रक, विद्यार्थिनीचे कार्ड, एखादी किंमत-यादी. प्रत्येक cache hit म्हणजे एक Lambda run कमी, एक database read कमी, आणि जलद उत्तर. पण TTL संपेपर्यंत cache जुनी उत्तरेही देतो, आणि चुकीची cache key दुसऱ्याचे उत्तर देते. दोन्ही खरोखर घडलेल्या incidents आहेत.

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

Gateway._handle() (apigw/gateway.py) मध्ये, TTL असलेल्या stage वरचा (prod वर CACHE_TTL = 300, dev वर 0) cache=True असलेला route (stage, method, path, sorted query) पासून key बनवतो. TTL पेक्षा कमी वयाचे साठवलेले उत्तर X-Cache: Hit सह परत दिले जाते आणि integration ला call होत नाही; नाहीतर तो Miss असतो, आणि 200 उत्तर साठवले जाते. फक्त 200s साठवले जातात. apigw/demo.py मधले बनावट Clock demo ला क्षणात 301 सेकंद पुढे उडी मारू देते. लक्षात ठेवा: हे model प्रत्येक query string key मध्ये घालते; खरे API Gateway फक्त तुम्ही निवडलेल्याच वापरते.

🧪 करून पाहा

python3 apigw/demo.py cache
python3 - <<'EOF'
import sys; sys.path.insert(0, "apigw"); from demo import office, Clock, calls
c = Clock(); gw, _ = office(c, cache_ttl=60); calls["n"] = 0
for path, q in (("/students/7", {}), ("/students/7", {}), ("/students/7", {"lang": "mr"}), ("/students/9", {}), ("/students/404", {}), ("/students/404", {})):
    st, hd, _ = gw.handle("GET", path, query=q)
    print(f"{path:<14} {str(q):<16} {st} {hd.get('X-Cache')}  kitchen calls: {calls['n']}")
c.t += 61; print("after 61 s:", gw.handle("GET", "/students/7")[1], "kitchen calls:", calls["n"])
print({k: gw.metrics[k] for k in ("CacheHitCount", "CacheMissCount")})
EOF

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

cache हे छापते:

   +0   s  200 Miss   kitchen calls so far: 1
   +10  s  200 Hit   kitchen calls so far: 1
   +200 s  200 Hit   kitchen calls so far: 1
   +301 s  200 Miss   kitchen calls so far: 2

(वेळा बेरीज होत जातात: चौथी request 511 s ला आहे, म्हणजे 0 s ला साठवलेल्या उत्तराच्या 300 s TTL च्या पलीकडे).

तुमचा snippet (TTL 60 s) /students/7 साठी आधी Miss मग Hit छापतो (1 kitchen call), {'lang': 'mr'} साठी Miss (नवी key → 2 calls), /students/9 साठी Miss (3 calls), आणि /students/404 साठी दोनदा 404 Miss (4 आणि 5 calls — errors साठवले जात नाहीत). मग after 61 s: {'X-Cache': 'Miss'} kitchen calls: 6 आणि {'CacheHitCount': 1, 'CacheMissCount': 6}.

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

तुम्ही प्रत्येक hit आणि miss आधीच सांगू शकता: तीच key आणि TTL पेक्षा कमी वय → फलक उत्तर देतो; नवी query, नवा path, एखादी error, किंवा जुनी चिठ्ठी → kitchen ला विचारले जाते.

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

प्रत्येक user चा वेगळा route (/students/me, Authorization header वापरणारे काहीही) तो header cache key मध्ये न घालता cache करणे — users ना एकमेकांचा data दिसतो
invalidation सगळ्यांसाठी खुले ठेवणे — कोणीही max-age=0 ने cache टाळू शकतो
शांत API वर मोठा cache — त्याचे दर तासाला bill होते
write (POST /marks) cache केलेला GET साफ करेल अशी अपेक्षा — तसे होत नाही; TTL छोटा ठेवा किंवा cache flush करा

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

खऱ्या account वर — prod साठी 0.5 GB cache चालू करा, एक method 300 s साठी cache करा, आणि तो flush करा:

aws apigateway update-stage --rest-api-id abc123 --stage-name prod --patch-operations \
    op=replace,path=/cacheClusterEnabled,value=true \
    op=replace,path=/cacheClusterSize,value=0.5 \
    op=replace,path=/~1students~1{id}/GET/caching/enabled,value=true \
    op=replace,path=/~1students~1{id}/GET/caching/ttlInSeconds,value=300
aws apigateway flush-stage-cache --rest-api-id abc123 --stage-name prod

Terraform — त्याच route साठी method settings:

resource "aws_api_gateway_method_settings" "student_cache" {
  rest_api_id = aws_api_gateway_rest_api.school.id
  stage_name  = aws_api_gateway_stage.prod.stage_name
  method_path = "students/{id}/GET"
  settings {
    caching_enabled                         = true
    cache_ttl_in_seconds                    = 300
    require_authorization_for_cache_control = true
  }
}

🏭 Production मध्ये हे का महत्त्वाचे आहे: सगळ्यांसाठी सारखे असेल तेवढेच cache करा, key विचारपूर्वक निवडा, hit ratio पाहत राहा (CacheHitCount ÷ सगळ्या cached requests), आणि ratio कमीच राहिला तर cache काढून टाका — त्याचे पैसे तुम्ही दर तासाला भरता.

⏭️ पुढे

Office जलद उत्तर देते. पण दुसऱ्या site वरचे एक web page त्याला call करू इच्छिते, आणि browser आधी परवानगी विचारतो — CORS.

git checkout lesson-09-cors

📌 Lesson 08 — Caching: the notice board

📍 You are here: Lesson 08 of 12 · Previous: lesson-07-throttling · Next: lesson-09-cors

📦 What's in this branch

Lessons 01–07, plus the stage cache: the office answers a repeated GET from its notice board until the TTL runs out, and the kitchen is asked only once. You will see the cache key at work and why per-user answers must never share one. cache() in apigw/demo.py asks for the same student four times over five minutes.

🧒 Explain like I'm 5

Many parents ask the clerk the same question: "Which class is Aishwarya in?" The first time, the clerk walks to the kitchen and asks. Then the clerk pins the answer on the notice board 📌 with a note: "good for 5 minutes".

The next parent asks — the clerk reads the board. No walk to the kitchen. After 5 minutes the note is too old, so the clerk takes it down and asks the kitchen again.

The board is organised by the exact question. "Aishwarya's class" and "Aishwarya's class, in Marathi" are two different notes. And the clerk must never pin "my marks" on the board — the next parent would read someone else's marks.

🗺️ Diagram

flowchart LR
    q0["+0 s GET /students/7"] -->|"Miss"| k["🍳 kitchen<br/>calls = 1"]
    k --> board["📌 notice board<br/>key: prod GET /students/7<br/>good until +300 s"]
    q1["+10 s"] -->|"Hit"| board
    q2["+210 s"] -->|"Hit"| board
    q3["+511 s — TTL passed"] -->|"Miss"| k2["🍳 kitchen<br/>calls = 2"]

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

❓ What

Stage cache — REST APIs only. You turn it on per stage and choose a size (0.5 GB up to 237 GB). It is billed per hour by size, whether it is used or not — roughly $0.02 per hour for 0.5 GB, about $15 a month (approximate; check your Region).
TTL — how long an answer stays: 300 seconds by default, from 0 to 3600. 0 turns caching off. You can change it per method.
Cache key — by default the method and resource path. You choose which query strings and headers also go into the key. Only GET is cached by default.
Invalidation — flush the whole stage cache, or let a client send Cache-Control: max-age=0 to fetch a fresh answer. Turn on require authorization so only callers with execute-api:InvalidateCache can do this; otherwise anyone can make your cache useless.
Metrics — CacheHitCount and CacheMissCount (lesson 11).
HTTP APIs have no cache: put CloudFront in front, or cache in the application.

🤔 Why

Because many APIs read the same thing again and again — a timetable, a student card, a price list. Each cache hit is one less Lambda run and one less database read, and a faster answer. But a cache also returns old answers until the TTL passes, and a wrong cache key returns someone else's answer. Both are real incidents.

🔧 How (in this repo)

In Gateway._handle() (apigw/gateway.py) a route with cache=True on a stage with a TTL (CACHE_TTL = 300 on prod, 0 on dev) builds a key from (stage, method, path, sorted query). A stored answer younger than the TTL is returned with X-Cache: Hit and the integration is not called; otherwise it is a Miss, and a 200 answer is stored. Only 200s are stored. The fake Clock in apigw/demo.py lets the demo jump 301 seconds in no time. Note: this model puts every query string into the key; real API Gateway uses only the ones you choose.

🧪 Try it

python3 apigw/demo.py cache
python3 - <<'EOF'
import sys; sys.path.insert(0, "apigw"); from demo import office, Clock, calls
c = Clock(); gw, _ = office(c, cache_ttl=60); calls["n"] = 0
for path, q in (("/students/7", {}), ("/students/7", {}), ("/students/7", {"lang": "mr"}), ("/students/9", {}), ("/students/404", {}), ("/students/404", {})):
    st, hd, _ = gw.handle("GET", path, query=q)
    print(f"{path:<14} {str(q):<16} {st} {hd.get('X-Cache')}  kitchen calls: {calls['n']}")
c.t += 61; print("after 61 s:", gw.handle("GET", "/students/7")[1], "kitchen calls:", calls["n"])
print({k: gw.metrics[k] for k in ("CacheHitCount", "CacheMissCount")})
EOF

✅ Verify — what you should see

cache prints:

   +0   s  200 Miss   kitchen calls so far: 1
   +10  s  200 Hit   kitchen calls so far: 1
   +200 s  200 Hit   kitchen calls so far: 1
   +301 s  200 Miss   kitchen calls so far: 2

(the times add up: the fourth request is at 511 s, past the 300 s TTL of the answer stored at 0 s).

Your snippet (TTL 60 s) prints Miss then Hit for /students/7 (1 kitchen call), Miss for {'lang': 'mr'} (a new key → 2 calls), Miss for /students/9 (3 calls), and 404 Miss twice for /students/404 (4 and 5 calls — errors are not stored). Then after 61 s: {'X-Cache': 'Miss'} kitchen calls: 6 and {'CacheHitCount': 1, 'CacheMissCount': 6}.

🏁 What you just proved

You can predict every hit and miss: same key and younger than the TTL → the board answers; a new query, a new path, an error, or an old note → the kitchen is asked.

⚠️ Common mistakes

caching a per-user route (/students/me, anything using the Authorization header) without that header in the cache key — users see each other's data
leaving invalidation open to everyone — anyone can bypass the cache with max-age=0
a big cache on a quiet API — it is billed every hour
expecting a write (POST /marks) to clear the cached GET — it does not; keep the TTL short or flush the cache

🏭 In production

On a real account — turn on a 0.5 GB cache for prod, cache one method for 300 s, and flush it:

aws apigateway update-stage --rest-api-id abc123 --stage-name prod --patch-operations \
    op=replace,path=/cacheClusterEnabled,value=true \
    op=replace,path=/cacheClusterSize,value=0.5 \
    op=replace,path=/~1students~1{id}/GET/caching/enabled,value=true \
    op=replace,path=/~1students~1{id}/GET/caching/ttlInSeconds,value=300
aws apigateway flush-stage-cache --rest-api-id abc123 --stage-name prod

Terraform — method settings for the same route:

resource "aws_api_gateway_method_settings" "student_cache" {
  rest_api_id = aws_api_gateway_rest_api.school.id
  stage_name  = aws_api_gateway_stage.prod.stage_name
  method_path = "students/{id}/GET"
  settings {
    caching_enabled                         = true
    cache_ttl_in_seconds                    = 300
    require_authorization_for_cache_control = true
  }
}

🏭 Why this matters in production: cache only what is the same for everyone, choose the key on purpose, watch the hit ratio (CacheHitCount ÷ all cached requests), and remove the cache if the ratio stays low — you pay for it every hour.

⏭️ Next

The office answers fast. But a web page on another site wants to call it, and the browser asks permission first — CORS.

git checkout lesson-09-cors

← Previousthrottling Next →cors

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