¶ Your brief
The district list changes once a year, but KEZA’s districts API is slow (2.5 s). Every form load waits for it. New idea: response.cache (fetch only).
¶ How your teacher does it · Mocks → New Mock
1 · Request: GET /victor/keza/v1/districts
2 · Responses (the first matching rule wins)
Otherwise — when no rule above matches
Respond with 200 Body type jsonResponse delay 2500 ms
{
"districts": [
{
"code": "GASABO",
"name": "Gasabo",
"province": "Kigali"
},
{
"code": "KICUKIRO",
"name": "Kicukiro",
"province": "Kigali"
},
{
"code": "NYARUGENGE",
"name": "Nyarugenge",
"province": "Kigali"
},
{
"code": "HUYE",
"name": "Huye",
"province": "Southern"
},
{
"code": "MUSANZE",
"name": "Musanze",
"province": "Northern"
}
],
"generatedAt": "2026-09-26T08:00:00Z"
}
3 · Label
| Field | Value |
|---|---|
| Name | Victor KEZA Districts (slow) |
| Code | VICTOR_KEZA_DISTRICTS |
| Service | KEZA |
| Category | victor-course |
| Active | ✔ served by the mock server right away |
- A single rule with a response delay of 2500 ms simulates a slow partner. Use delays to rehearse timeouts too.
Districts mock: a fixed 2500 ms delay makes the cache visible
- The Otherwise card answers every districts call.
- Delay · Fixed 2500 ms: every uncached call takes at least 2.5 s.
¶ How your teacher does it · Endpoints → New Endpoint
| Field | Value | |
|---|---|---|
| **Endpoint adapter *** | FMAPPING (fetch) |
locked after save |
| **Endpoint code *** | VICTOR_KEZA_DISTRICTS_FETCH |
locked after save |
| **Endpoint url *** | http://mock-service-engine.apps:8000/victor/keza/v1/districts |
|
| **Endpoint type *** | FETCH (set by the adapter) |
|
| **Endpoint name *** | Victor KEZA Districts |
|
| **Partner *** | KEZA |
locked after save |
| Active | ON |
|
| **Endpoint description *** | Victor course: cached district list (response cache). |
**Endpoint Mapping ***
{
"method": "GET",
"response": {
"cache": { "enabled": true, "ttl": 300 }
}
}
- cache.enabled + ttl in seconds (default 300). The cache key is the endpoint code plus a hash of the outgoing request, so different inputs are cached separately.
¶ First call (cache miss) · fetch/sync · VICTOR_KEZA_DISTRICTS_FETCH
HTTP 200 3.28 s captured on staging · 26 Sep 2026
1 · Request (curl)
curl -s -X POST "https://integration-gateway.staging.iremboinc.com/integration/v1/fetch/sync" \
-H "Authorization: Bearer $TOKEN" \
-H "portal: integration-management-portal" \
-H "Content-Type: application/json" \
-d '{
"endpointCode": "VICTOR_KEZA_DISTRICTS_FETCH",
"callerId": "victor-course",
"requester": "victor-course",
"payload": {}
}' | jq
2 · Real response
{
"status": true,
"responseCode": "integration_870000",
"responseMessage": "integration_870000",
"data": {
"id": "54e82c91-b79e-4878-bca1-342310c9666a",
"endpointCode": "VICTOR_KEZA_DISTRICTS_FETCH",
"callerId": "victor-course",
"response": "{\n \"districts\": [\n {\n \"code\": \"GASABO\",\n \"name\": \"Gasabo\",\n \"province\": \"Kigali\"\n },\n {\n \"code\": \"KICUKIRO\",\n \"name\": \"Kicukiro\",\n \"province\": \"Kigali\"\n },\n {\n \"code\": \"NYARUGENGE\",\n \"name\": \"Nyarugenge\",\n \"province\": \"Kigali\"\n },\n {\n \"code\": \"HUYE\",\n \"name\": \"Huye\",\n \"province\": \"Southern\"\n },\n {\n \"code\": \"MUSANZE\",\n \"name\": \"Musanze\",\n \"province\": \"Northern\"\n }\n ],\n \"generatedAt\": \"2026-09-26T08:00:00Z\"\n}",
"adapterCode": "FMAPPING"
},
"timestamp": "2026-09-26T09:48:23.354007031",
"traceId": "6ab778c4a229fd36583025067d67e31a"
}
3 · Decoded data.response
{
"districts": [
{
"code": "GASABO",
"name": "Gasabo",
"province": "Kigali"
},
{
"code": "KICUKIRO",
"name": "Kicukiro",
"province": "Kigali"
},
{
"code": "NYARUGENGE",
"name": "Nyarugenge",
"province": "Kigali"
},
{
"code": "HUYE",
"name": "Huye",
"province": "Southern"
},
{
"code": "MUSANZE",
"name": "Musanze",
"province": "Northern"
}
],
"generatedAt": "2026-09-26T08:00:00Z"
}
4 · What to notice
- 3.28 s: the 2.5 s mock delay plus the normal round trip. The answer is now cached.
¶ Second call (cache hit) · fetch/sync · VICTOR_KEZA_DISTRICTS_FETCH
HTTP 200 0.62 s captured on staging · 26 Sep 2026
1 · Request (curl)
curl -s -X POST "https://integration-gateway.staging.iremboinc.com/integration/v1/fetch/sync" \
-H "Authorization: Bearer $TOKEN" \
-H "portal: integration-management-portal" \
-H "Content-Type: application/json" \
-d '{
"endpointCode": "VICTOR_KEZA_DISTRICTS_FETCH",
"callerId": "victor-course",
"requester": "victor-course",
"payload": {}
}' | jq
2 · Real response
{
"status": true,
"responseCode": "integration_870000",
"responseMessage": "integration_870000",
"data": {
"id": "7cf7af37-0171-482a-8dde-b34785643363",
"endpointCode": "VICTOR_KEZA_DISTRICTS_FETCH",
"callerId": "victor-course",
"response": "{\n \"districts\": [\n {\n \"code\": \"GASABO\",\n \"name\": \"Gasabo\",\n \"province\": \"Kigali\"\n },\n {\n \"code\": \"KICUKIRO\",\n \"name\": \"Kicukiro\",\n \"province\": \"Kigali\"\n },\n {\n \"code\": \"NYARUGENGE\",\n \"name\": \"Nyarugenge\",\n \"province\": \"Kigali\"\n },\n {\n \"code\": \"HUYE\",\n \"name\": \"Huye\",\n \"province\": \"Southern\"\n },\n {\n \"code\": \"MUSANZE\",\n \"name\": \"Musanze\",\n \"province\": \"Northern\"\n }\n ],\n \"generatedAt\": \"2026-09-26T08:00:00Z\"\n}",
"adapterCode": "FMAPPING"
},
"timestamp": "2026-09-26T09:48:24.009156254",
"traceId": "6ab778c7eb5c62936538b799f8dc151c"
}
3 · Decoded data.response
{
"districts": [
{
"code": "GASABO",
"name": "Gasabo",
"province": "Kigali"
},
{
"code": "KICUKIRO",
"name": "Kicukiro",
"province": "Kigali"
},
{
"code": "NYARUGENGE",
"name": "Nyarugenge",
"province": "Kigali"
},
{
"code": "HUYE",
"name": "Huye",
"province": "Southern"
},
{
"code": "MUSANZE",
"name": "Musanze",
"province": "Northern"
}
],
"generatedAt": "2026-09-26T08:00:00Z"
}
4 · What to notice
- 0.62 s with identical content: KEZA was not called.
- For the next 300 s every identical request is served from the cache.
Gotcha · Cache only what is safe to be stale
- Good: reference lists (districts, programmes, fees that change rarely).
- Bad: eligibility, balances, anything personal or time-sensitive.
- After changing the mapping or the partner data, remember that cached answers live until their TTL ends.
- Push endpoints ignore
cache.
¶ Check yourself
A colleague enables cache with ttl 86400 on the eligibility endpoint. An applicant turns 36 today (the age limit is 35). What can go wrong?
- A. Nothing: the cache key includes the current date
- B. They may be told they are eligible for up to 24 h
- C. The endpoint rejects the call once the TTL passes
- D. Their push requests are cached for 24 h as well
Show the answer
B. The same request returns the cached answer until the TTL expires. Never cache decisions that can change.
Your turn · measure the cache
Copy the districts mock (keep the 2500 ms delay) to
/${your_first_name}/keza/v1/districtsand create${YOUR_FIRST_NAME}_KEZA_DISTRICTS_FETCHwith"ttl": 60. Replace the variables before saving (Aline →ALINE_…,/aline/…). Add-w '%{time_total}\n'to your curl.Done when: call 1 takes more than 2.5 s, call 2 under 1 s, and a call after 60 s is slow again. Write the three times in your evidence pack.
← 4.3 Accept “errors” that mean success: safe enrollment · 5.1 Send files: attachment markers →