Model resources around analytical questions
Useful resources include channel performance, campaign performance, landing-page performance, search visibility, referral sources, funnels, and data quality. Do not simply expose a vendor table because it is easy to query. A source-shaped service makes every consumer learn vendor-specific schemas and makes cross-source reporting difficult.
Declare the row grain in documentation and response metadata. Unsupported dimension combinations should fail clearly instead of returning duplicated or non-additive measures.
Define a stable response envelope
{
"resource": "channel-performance",
"grain": ["date", "site", "channel"],
"data_through": "2026-10-24T23:59:59-07:00",
"definition_version": "2026.10",
"quality": {"status": "complete", "coverage": 1.0},
"rows": [{"date": "2026-10-24", "channel": "Organic Search",
"sessions": 24830, "qualified_visits": 6734}]
}The response should identify the resource, applied grain, reporting context, freshness, definition version, and quality status. Null should mean unavailable or not applicable; zero should mean a measured absence. Units and currencies must be explicit.
Make queries declarative and reproducible
Support a controlled set of date, dimension, metric, filter, sort, and pagination parameters. Validate combinations before expensive work begins. Normalize requests so identical queries can be cached and reproduced. Define whether a filter applies before aggregation, after aggregation, or to a source-specific field.
- Use ISO dates and an explicit reporting timezone.
- Allowlist metrics and dimensions rather than accepting arbitrary expressions.
- Return the normalized request with the response.
- Use cursor pagination when result ordering can change.
Return freshness and partial-result states
Recent data can be revised because of late events, attribution processing, thresholding, cost reconciliation, or mapping updates. Return a data-through timestamp, extraction time, source status, and finalization state. If a source is delayed or limited, identify the affected resource and set a partial flag.
Do not hide source row limits or sampling behavior. A top-rows response should not appear exhaustive. Include the applied limit, whether more data may exist, and a supported export path for larger extracts.
Expose quality and reconciliation
Provide a quality resource with source coverage, latest complete partition, schema status, duplicate status, unmapped values, and reconciliation results. Dashboards can use it to warn users before they act on incomplete data.
Reconciliation compares source totals with modeled totals at a supported grain and tolerance. The goal is not forced equality across unlike systems; it is evidence that known differences are understood and unexplained differences are investigated.
Version behavior and secure access
Changing a metric formula, channel mapping, null behavior, or historical restatement can be breaking even if the JSON shape remains the same. Classify changes, publish effective dates, and support overlapping versions during migration.
Scope access by resource, site, and sensitivity. Aggregate endpoints should not expose identity fields simply because a raw table contains them. Log administrative changes and large exports, rotate credentials, and monitor latency, error rate, source failures, and usage.
