A Practical Cache Policy for Changing Water Readings
From the earlier reference collection. Read the current software blog.
Choose cache lifetime from observed update cadence and request cost, refresh safely, and show retrieval age so readers can interpret changing readings.
Start with how the value changes
A useful cache policy begins with evidence about the source: how often it publishes new readings, whether it exposes a revision marker, and what the cost of a refresh is. A rapidly changing value may deserve a short cache lifetime, while a source that updates infrequently gains little from repeated requests. Do not guess that a page is live simply because its subject changes over time.
Distinguish source observation time from your retrieval time. A cached value fetched five minutes ago could describe a measurement from much earlier. Displaying both, when available, avoids conflating freshness of the cache with freshness of the underlying reading.
Choose a safe refresh pattern
Use a cache lifetime that matches the source’s observed publication cadence and the user impact of staleness. Add a minimum interval to prevent accidental request bursts. If the source provides conditional requests, such as validators documented by that source, they can help check for changes without repeatedly downloading an unchanged representation; do not assume those validators exist.
Refresh into a candidate value, validate it, and then replace the active cache atomically. If retrieval or parsing fails, preserve the last valid reading and its timestamps. Record that the refresh failed so the application does not make old data appear newly current.
Balance responsiveness and cost
Consider three costs: a stale display can mislead; frequent requests consume bandwidth and may burden the source; and shorter caching can increase operational fragility when a source is intermittent. A small table of observed update times over several days can guide an initial interval. Review it when the source behavior or user need changes rather than treating the choice as permanent.
For example, if observations usually arrive in broad intervals, polling many times within that interval may rarely change the displayed value. A longer cache with an explicit age could be clearer than a rapid refresh that repeatedly returns the same reading. If the value is used for a time-sensitive decision, the acceptable age may be shorter, but that is a product requirement to state.
Expose the age honestly
Show when the reading was observed, when it was retrieved, and whether the latest refresh succeeded. If only retrieval time is known, label it as such. Avoid a “current” badge that implies a measurement time the system cannot verify.
A water temperature resource is a practical example for evaluating this policy: readers can ask whether a value’s age is visible and how much delay would matter for their use. The page itself does not establish a supported API, polling allowance, or sensor cadence; those must come from the source’s own information.