¶ Why we build the mock first
KEZA’s test environment is not ready, and even when it is, you cannot ask KEZA to make a learner “not eligible” on demand. A mock is a fake KEZA served by the IremboHub mock server. You decide exactly which request gets which answer, so you can test every case in the worksheet, today.
¶ How the mock server picks an answer
Every mock is one method + URL path with an ordered list of rules.
¶ Step · 1 · Match method and path
A request must match the mock’s method (GET, POST…) and URL path. {name} in a path matches any value in that segment.
¶ Step · 2 · Try the rules top to bottom
Each rule has conditions on Header, Query param, Path variable or Body. All conditions in a rule must match (AND).
¶ Step · 3 · First match wins
The first rule whose conditions all match returns its status code and body. So put the most specific rules first.
¶ Step · 4 · Otherwise
If no rule matches, the Otherwise response is returned. Make it the partner’s “unauthorized” or “bad request” answer.
New Mock form, filled for a demo
- Start from Blank or a template.
- 1 · Request: method and URL path, without the /mock prefix.
- Add rule: one rule per case in the partner contract.
- Conditions: header, query, path variable or body; all must match.
- Status code of this rule.
- Response body (JSON).
- Dynamic response: reuse request values with templates.
- Otherwise: the answer when no rule matches.
- 3 · Label: name, auto-generated code, service, category.
- Advanced options: delay, scenarios, precedence over file stubs.
- Save: the mock server reloads (wait a few seconds).
¶ Mock 1 · the KEZA login
How your teacher does it: in Mocks → New Mock, start from Blank and fill the three sections exactly like this:
¶ How your teacher does it · Mocks → New Mock
1 · Request: POST /victor/keza/v1/auth/login
2 · Responses (the first matching rule wins)
Rule 1 · Valid Irembo credentials
| Match on | Key | Operator | Value | |
|---|---|---|---|---|
| If | Body | username | equals | irembo-integration |
| and | Body | password | equals | Keza@2026 |
Respond with 200 Body type json
{
"status": "SUCCESS",
"data": {
"token": "keza-victor-token-7f3a",
"tokenType": "Bearer",
"expiresIn": 3600
}
}
Otherwise — when no rule above matches
Respond with 401 Body type json
{
"status": "FAILED",
"code": "INVALID_CREDENTIALS",
"message": "Username or password is incorrect."
}
3 · Label
| Field | Value |
|---|---|
| Name | Victor KEZA Login |
| Code | VICTOR_KEZA_LOGIN |
| Service | KEZA |
| Category | victor-course |
| Active | ✔ served by the mock server right away |
- Two Body conditions: the engine must send exactly this username and password. Anything else falls to Otherwise. The password is a fake training value that lives only in this mock.
- The success body has the token at
data.token— the path from the worksheet. - Otherwise → 401: wrong credentials behave like the real KEZA.
¶ Mock 2 · KEZA eligibility
Four rules, one per worksheet case. Every rule checks the bearer token, so an unauthenticated call can only reach Otherwise.
¶ How your teacher does it · Mocks → New Mock
1 · Request: GET /victor/keza/v1/eligibility
2 · Responses (the first matching rule wins)
Rule 1 · Eligible learner
| Match on | Key | Operator | Value | |
|---|---|---|---|---|
| If | Header | Authorization | equals | Bearer keza-victor-token-7f3a |
| and | Query param | nationalId | equals | 1199880012345678 |
| and | Query param | program | equals | DATA_ANALYTICS |
Respond with 200 Body type json
{
"found": true,
"learner": {
"nationalId": "1199880012345678",
"firstName": "Aline",
"lastName": "Mukamana",
"district": "Gasabo"
},
"eligibility": {
"status": "ELIGIBLE",
"programCode": "DATA_ANALYTICS",
"reasonCode": null,
"evaluatedAt": "2026-09-26T08:00:00Z"
}
}
Rule 2 · Not eligible learner
| Match on | Key | Operator | Value | |
|---|---|---|---|---|
| If | Header | Authorization | equals | Bearer keza-victor-token-7f3a |
| and | Query param | nationalId | equals | 1199770098765432 |
Respond with 200 Body type json
{
"found": true,
"learner": {
"nationalId": "1199770098765432",
"firstName": "Eric",
"lastName": "Habimana",
"district": "Huye"
},
"eligibility": {
"status": "NOT_ELIGIBLE",
"programCode": "DATA_ANALYTICS",
"reasonCode": "AGE_LIMIT",
"evaluatedAt": "2026-09-26T08:00:00Z"
}
}
Rule 3 · Authenticated but unknown learner
| Match on | Key | Operator | Value | |
|---|---|---|---|---|
| If | Header | Authorization | equals | Bearer keza-victor-token-7f3a |
Respond with 404 Body type json
{
"found": false,
"code": "LEARNER_NOT_FOUND",
"message": "No learner matches the supplied National ID."
}
Otherwise — when no rule above matches
Respond with 401 Body type json
{
"code": "UNAUTHORIZED",
"message": "Missing or invalid bearer token."
}
3 · Label
| Field | Value |
|---|---|
| Name | Victor KEZA Eligibility |
| Code | VICTOR_KEZA_ELIGIBILITY |
| Service | KEZA |
| Category | victor-course |
| Active | ✔ served by the mock server right away |
- Rule 1 is the most specific (token + Aline + program), so it goes first.
- Rule 2 (Eric) returns 200 with
NOT_ELIGIBLE, exactly as the KEZA guide says. A business refusal is not an HTTP error here. - Rule 3 has only the token condition: any other authenticated learner gets 404 LEARNER_NOT_FOUND.
- Otherwise → 401: no token, wrong token.
Press Save with Active switched on. The portal confirms “Success! Mock has been created and applied to the mock server”. The mock is now live at http://mock-service-engine.apps:8000/victor/keza/v1/eligibility — an address only the engine can reach, not your laptop.
Gotcha · Four mock mistakes we see often
- Wrong rule order: a broad rule (token only) above a specific one hides it forever.
- Duplicate signature: two active mocks with the same method, path and conditions are rejected (409). Use your prefix.
- Reserved path: never put a mock under a path containing
/mock/endpoints/; the mock server already uses it.- “Request was not matched” right after saving: the mock server is still reloading. Wait a few seconds and retry before debugging.
¶ Check yourself
You add a rule “Suspended learner” (token + nationalId = 1199660011112222 → 403). Where must it go?
- A. Anywhere: the mock server picks the best match
- B. Above rule 3, which matches any token
- C. Below rule 3, so the general rules run first
- D. In the Otherwise card, as a fallback
Show the answer
B. First match wins. Rule 3 only checks the token, so it would catch the suspended learner before a rule placed below it.
Your turn · build both mocks with your prefix
- Create
${YOUR_FIRST_NAME}_KEZA_LOGINonPOST /${your_first_name}/keza/v1/auth/loginwith the same two body conditions.- Create
${YOUR_FIRST_NAME}_KEZA_ELIGIBILITYonGET /${your_first_name}/keza/v1/eligibilitywith the four rules in the same order.- Keep them: your endpoint in the next lesson calls them.
Replace the variables before saving (e.g.
ALINE_KEZA_LOGIN,/aline/keza/v1/auth/login).
← 1.3 Read a partner contract: the KEZA worksheet · 1.5 Your first endpoint, with login authentication →