analytics scope.
Pick a window
Every endpoint takes one optionalrange:
range you asked for is echoed back, so a stored response is self-describing.
The shape of a response
Each endpoint returns one or more panels. A panel is either a set of summary cards or a time series, and the response always names the range it covers.A panel can come back
null. Each one is computed independently, so a slow or unavailable source degrades that panel rather than failing the whole call. Treat null as “not available for this window”, not as zero — and read a missing panel differently from an empty one.Buckets in a time series
Series are bucketed by the window, and the bucket is named in the payload rather than implied:mode tells you how to read date — W31 is an ISO week, a 08/18 is a day. Read mode rather than pattern-matching the label, since the same endpoint switches bucket as the range widens.
Deltas
Card values often carry a comparison against the previous window of the same length:deltaPercentage is null when there is no comparable previous window — a new workspace, or a range that reaches past the available history. Render that as “no comparison” rather than 0%.
Putting it in a dashboard
1
Fetch the areas you show, in parallel
The five endpoints are independent; nothing needs to be called in order.
2
Handle null panels per panel
One unavailable source should blank one card, not the page.
3
Read `mode` before formatting dates
It changes with the range.
4
Cache for the window you display
These are roll-ups over days; polling them frequently spends rate limit for numbers that barely move.