What does it mean that a geo API "fails closed"?
That the failure is visible. An API that fails open answers 200 with an empty list when something has gone wrong, and that answer is impossible to tell apart from an honest "there is nothing here".
We have measured that failure fifteen times in sources we use ourselves. A sample:
- A government service answered zero civil defence shelters for 174 municipalities — not because they had none, but because we had not fetched them. The zero looked like an answer.
- A geological service silently ignored the
?kommunkod=parameter and returned all 836,435 wells in the country. The filter looked like it worked: the number changed. - A map service accepted a coordinate reference system it did not support and answered empty instead of failing. Ten points across five municipalities went invisible.
What we do instead
Empty is an answer; a failure is a failure. Question got through and the world is empty: 200 with an empty list. Question did not get through: 502/503 with a skal (reason) field.
null means unmeasured. entydig: null means ambiguity could not be measured for this query — not that the name is unique. hojd_m: null with nodata: true means no elevation data — not sea level.
A ceiling is not a count. antal is rows in the response; total is how many exist, counted before the limit, and avkortad says the cap cut the list.
"Not fetched" is unknown. Registers we fetch per municipality carry a state field. If the municipality has not been swept, the count is unknown, not zero.
An image that cannot be filled is not sent. 503 with lagsta_fyllande_zoom beats a map with holes, every time.
What it costs you as a consumer
Two more lines of code, and a few answers that are not answers. In exchange your service can tell "nothing happened" apart from "we don't know", which is the difference between a correct page and a page that lies quietly. The full contract: the error contract.