ai-coding-minesIndexGitHub

The list labelled "all statuses" was not all of them

Write APIs

Symptom

On an API where the list endpoint requires a status filter, records in one band never appear. They exist, but no combination of filters returns them.

Cause

One status was missing from the filter list — a short-lived intermediate band ("tracking number entered, not yet scanned by the carrier").

★ Worse: that list had been written down six months earlier as "expanded to all statuses". It actually contained a similarly-named value (NONE) and omitted the real one (NONE_TRACKING). Because it said "all", nobody checked it again.

Cost

Orders in that band were unfindable for two days. They needed action.

Fix

★★ On a list API with a mandatory filter, a value you omitted is a record that does not exist.

Suspect the filter before concluding "there are none".

The other side is blocked too

Records in that band are invisible to the query but may already be fully processed. Assume they are unprocessed and retry the write, and you get INVALID_STATUS. Invisible and unprocessed are different things.

A list with a required filter shows only that parameter's value space

On a list endpoint where the status filter is mandatory, any value you can't enumerate is a band you will never see. When you need everything, don't fix the list; find a filter-free single-record path. The single-record path returned regardless of status, and carried fields the list never had.

Two paths built from the same segments are different resources. /{parent}/{id}/child and /{parent}/child/{id} differ only in order; one takes an order ID, the other expects a different kind of ID and returns 400. Segment order is part of the identifier.