Singapore API workshops: distinguish an empty lookup from a failed request

The problem

A Singapore junior developer’s application shows no results after any API failure, so a user cannot distinguish a valid empty lookup from expired authentication, unavailable permission or a request limit.

Ask whether a result exists before counting its matches

A display with no rows can mean different things. First determine whether the request produced a valid result under the relevant service’s documented contract; only then ask whether that result contains matching data. An exception or an unclassified response supplies no evidence that the requested information is absent. Keep these two questions visible in a review note instead of converting every unsuccessful path into an empty list. An HTTP status, decoded body or application field may matter under the actual contract, so identify what the exercise uses to establish a result. Do not impose one endpoint’s structure on another. The decision to examine here is the client’s explanation of the outcome, not whether a real address exists or whether every dataset record has been downloaded.

Use the recorded failure categories within their scope

The recorded OneMap reverse-geocoding documentation distinguishes authentication, permission and quota failures from address results. That narrow example supports preserving failure as failure; it does not classify your application merely because its screen is empty. Locate the applicable response description for the service you are discussing and identify which part of a permitted example supports your interpretation. If you cannot establish whether the response is a valid result, record it as unclassified and ask for the missing contract detail. This guide supplies no current quota allowance, token, universal status mapping or instruction to retry. A missing field inside an otherwise valid record is also a different question from whether the whole request failed. The existing missing-location and venue-confirmation guides retain their specific field and arrival decisions.

• OneMap: Reverse Geocode ↗ · Source checked 20 October 2026

Prepare controlled examples with enough evidence to distinguish them

For an offered review, prepare three synthetic cases: a valid result with a match, a valid result without a match, and the relevant request failure. State the invented exercise contract that makes each classification possible. Include only the minimal input description, outcome evidence, present display and intended display. An empty list without the result-validity evidence cannot serve as the whole test. These examples are fixtures for discussion, not copied responses promised by every API. Use safe stand-ins instead of tokens, personal addresses, customer records or private logs. You do not need to exhaust a real quota, invalidate someone’s credentials or make a production request to demonstrate the classification issue. Check that the actual session permits the example and the form of feedback you want.

Work through an invented three-case client review

All cases and interface wording here are fictional. The practice contract says a completed lookup can provide one match or a valid no-match result, while a declared permission failure provides no valid lookup result. Case A completes with one synthetic match: show that result. Case B completes with a valid no-match outcome: explain that this lookup found no match. Case C declares permission failure: explain that the lookup could not be completed, rather than reporting no match. The present practice client shows “No match” for B and C. Comparing the contract and display therefore identifies C as the incorrect classification. B needs no change on that evidence. The bounded proposal is to preserve C’s failure state and review its explanation separately. This resolves the demonstrated distinction without proving an actual endpoint’s behaviour, an implementation or a suitable recovery procedure.

Keep an earlier displayed result separate from the failed lookup

Add the sequence if it affects what the user sees. In another invented example, the client first completes a permitted lookup and displays a synthetic match. A later lookup fails, but the old row remains beneath a no-match message. The earlier row is evidence of the earlier completed request; it cannot become a result of the failed request simply by staying on screen. Ask what the interface communicates about the current attempt and any retained previous result. Keeping an older result available might be useful in a particular product, but its meaning must be clear in that actual design. Do not infer that clearing every row is always the correct fix. This is a classification and explanation question, separate from pagination completeness or deciding whether a report uses a live dataset snapshot.

Match the next action to what the outcome establishes

Review the explanation and the proposed next step together. A confirmed no-match result may justify checking the permitted query or input; an authentication or permission failure has not established that a different search term will find data. Identify who can address the actual system condition and what the service’s documented process permits. Do not tell a user to disclose credentials or repeatedly retry merely to make an error disappear. A safe general message can avoid exposing internal details while the client still keeps the classification needed for correct handling. The fictional permission case establishes failure, but leaves its authorised recovery process unanswered. Record that as a separate enquiry. Changing the message is not evidence that access has been restored or that a new request would succeed.

Ask peers one question the examples can answer

An unsent review question could be: “Under this stated practice contract, which of these three displays wrongly describes whether a lookup result exists, and what evidence decides that?” Supply the synthetic cases and the intended user task, then ask about a recovery route only when its actual conditions are available. A general demonstration of successful requests may not offer an individual code-review slot. Confirm whether the organiser accepts failure-state questions and what example can be shown. Use the debugging-clinic guide when you need to reduce a reproducible failure, and the code-review test-boundary guide when the question becomes which behaviour an actual test should assert. This guide keeps the earlier classification decision small enough to discuss without disclosing the whole application.

Record what was checked and what remains unproved

Keep a result note with the fixture’s stated contract, expected classification, visible explanation, observation and unresolved condition. In the invented review, A shows the match, B shows the valid no-match explanation, and C was previously labelled no match despite its declared failure. The agreed next task is to exercise a revised C display while retaining checks for A and B. Until that exercise is actually run, the note records a proposed check, not a passed test. When a permitted run happens, retain the observation for each case rather than calling a single happy-path demonstration complete coverage. The actual service may require additional documented cases. Use Boardzip’s API workshop search to locate a suitable discussion after preparing the examples; the event topic does not establish the service contract or the finished repair.