Analytics and Metrics API

1) Why a separate API layer

Single truth for KPI: exclude "zoo SQL."

Product speed: fronts, partner panels, mobile customers get aggregates without direct access to DWH.
Security and compliance: tokenization, masks, geo-restrictions, RG/AML filters.
Scaling: cache, prerenders, CDN, stable contracts.

2) Taxonomy: metrics, dimensions, facts

Facts: bets, winnings, deposits, KYC events, RG interventions.
Dimensions: date/time (calendars), game/provider, brand/country, channel/device, player (token).
Metrics: GGR, NGR/NET, ARPPU, D1/D7/D30 retention, deposit frequency, anti-fraud FPR, RG risk.
Units: currency (FX), time (TZ), volume/counters (idempotent!).
KPI semantics: definitions in BI contracts, KPI versions are fixed.

3) Data & BI Contracts

Schema: fields, types, nullable, enum, units, currencies.
Semantics of metrics: formula, sources, aggregation windows, filters.
Compatibility (SEMVER): MAJOR breaks, MINOR adds fields, PATCH fixes.
DQ/SLA: freshness, completeness, consistency, discrepancy tolerances.
Privacy: 'pii: false', 'tokenized: true', prohibition of detokenization.

yaml api: analytics. v2 resource: /metrics/revenue kpi: GGR schema_version: 2. 1. 0 dimensions: [date, brand, country, provider, game]
metrics: [ggr, stakes, wins, bets_count]
sla: {freshness: PT15M, completeness: ">=99. 9%"}
privacy: {pii: false, tokenized: true}

4) Architecture

Query API (online aggregation over "gold "/cubes/fichestore).
Precompute API (scheduled prerenders, materialized views).
Events API (stream counters/signals).
Export API (signed uploads, WORM for audit).
Cache: in-memory → Redis → CDN, key = query hash + version.
Consistency: read-your-writes for final recordings, SLA freshness for aggregates.

5) Interface and requests

5. 1 Filters/aggregations/windows

'filter ': date ranges (' from/to'UTC, timezone aware), countries, brands, games, channels, devices.
'group _ by ': dimensions.
'metrics': list of KPIs.
`window`: `DAY|WEEK|MONTH|ROLLING_7D|ROLLING_28D`.
'currency ':' reporting'native', FX strategy: 'eod' intraday'txn'.
'sampling ': for heavy queries (only where allowed).

5. 2 Request example

json
POST /v2/metrics/revenue
{
"range": {"from":"2025-10-01","to":"2025-10-31","tz":"Europe/Kyiv"},
"group_by": ["date","brand","country"],
"metrics": ["ggr","bets_count","net_revenue"],
"filters": {"country":["EE","LT","LV"],"brand":["alpha","beta"]},
"currency": "reporting",
"window": "DAY"
}

5. 3 Example of response

json
{
"schema_version":"2. 1. 0",
"kpi_definitions":["ggr@1. 7. 0","net_revenue@1. 3. 2"],
"range":{"from":"2025-10-01","to":"2025-10-31","tz":"Europe/Kyiv"},
"data":[
{"date":"2025-10-01","brand":"alpha","country":"EE","ggr":12450. 72,"bets_count":182342,"net_revenue":10732. 11},
{"date":"2025-10-01","brand":"beta","country":"EE","ggr":...}
],
"fx":{"strategy":"eod","rate_date":"2025-10-31"},
"dq":{"freshness_sec":420,"completeness":0. 9992},
"trace_id":"3d1a-...-c79"
}

6) Pagination, limits, sorting

Pagination: 'limit' (≤10k), 'cursor' (opaque), sorting by dimensions/date.
Timeout/partial: partial responses for non-financial KPIs only; finance - either P200 or P504.
Rate limits: global/by key/by tenant; response contains'X-RateLimit- '.

7) Idempotence and cache

Idempotent GET/POST-read (with body) with'Idempotency-Key '.
Cache key = hash (parameters + schema version + role/tenant/geo).
TTL: KPI-dependent (e.g. 'PT15M' for revenue, 'PT5M' for events), reset with new snapshot.

8) Consistency and currency of time

Time-travel flag for retrospective reports (data versions).
Cut-off rules (day/week closing).
FX: we fix the strategy, the course date in the answer.
Clock: all timestamps are ISO-8601, TZ is required.

9) Security and privacy

mTLS/TLS1. 3, HMAC signature of request/response body (MITM/replay protection).
RBAC/ABAC/ReBAC: role + country + brand + purpose; default masks.
Multi-tenant - Isolate schemas/keys/quotas.
Tokenization of identifiers; PII prohibition in responses.
Audit: immutable request logs (WORM), 'trace _ id '/' actor '/' purpose'.
Consent/DSAR: filters on marketing attributes; "subject erased" flag.

10) RG/AML/Restriction antifrode

RG-policies: prohibition of issuing "aggressive" indicators for high-risk segments; units are safe.
AML/Antifraud: limited access to sensitive KPIs, zoning by role; separate endpoints for investigations.
Explainability: dictionary of explanations of KPI/signals for support.

11) Observability and SLO API

SLO: p95 latency (for example, ≤ 300 ms for cache hits; ≤ 2 s for heavy), success-rate ≥ 99. 5%.
DQ: freshness/completeness/integrity; labels in the response.
Usage: QPS, cache hit-rate, hot keys, validation errors.
Alerts: degradation of freshness, growth 4xx/5xx, anomalies according to KPI (unexpected zeros/peaks).
Tracing: 'trace _ id' end-to-end to DWH/fichestore.

12) Versioning and compatibility

Paths: '/v1 ', '/v2'; deprecate with migration window.
Schemas: 'schema _ version' in response; MAJOR → dual-read, migration guides.
KPI versions: in the response 'kpi _ definitions' with a link in the directory; Prevent hidden formula changes.

13) Errors and statuses

'400'validation (non-existent metric/measurement/filter combination).
'401/403'authentication/authorization.
'409'version/policy incompatibility.
'422'privacy/consent violation.
'429'quotas.
'5xx'platform failures (trace_id and retry seq.) .

json
{
"error":"VALIDATION_FAILED",
"message":"Unknown metric: ngrx",
"hint":"metrics allowed: ggr, net_revenue,...",
"trace_id":"..."
}

14) Integrations and interfaces

BI: pre-described semantic models, connectors (Looker/Power BI/Tableau) → API as a source.
ML: lightweight endpoints for feature units (point-in-time, without PII).
Partners: limited keys/quotas, geo-filters, reports only in aggregate blocks.

Webhook/Push: notifications "snapshot ready," "broken SLO/KPI range."

15) Examples of resource endpoints

15. 1 Revenue/Return

'POST/v2/metrics/revenue '→ GGR/NGR, bets/wins, measured by' date, brand, country, provider, game '.

15. 2 Retention and funnels

`POST /v2/metrics/retention` → когорты D1/D7/D30, `group_by=[cohort_week, brand, country]`.

15. 3 Payments

'POST/v2/metrics/payments' → deposits/withdrawals, average check, chargeback rate.

15. 4 Responsible Gaming

'POST/v2/metrics/rg '→ number of interventions, proportion of high-risk, mean reaction time.

15. 5 Antifraud

'POST/v2/metrics/antifraud '→ FPR/TPR, cases, losses prevented.

16) Testing and quality

Contract tests: enum/nullable/type, currency/time zone consistency.
DQ tests: control of ranges, monotony and integrity.
Regression: v1/v2 comparison on tolerances.
Load: peak profiles (tournaments/provider events).
Security: signatures, anti-replay, fuzzing requests, Zero-PII in logs.

17) Privacy by default

Aggregates with thresholds of "minimum N records" (k-anonymity).
No raw identifiers; tokens/categories only.
DSAR: API for unloading/deleting by token through a privileged loop.

18) Success Metrics (API KPIs)

Adoption: Proportion of reports/widgets using API rather than direct SQL.
Consistency - discrepancy between BI and tolerance ≤ API.
SLO: compliance with latency/success/freshness.
Security: zero PII cases in responses/logs.
Cost: hit-rate of the cache, cost of the request,% of prerenders.

19) RACI (example)

Product/Analytics (A) - KPI definitions, requirements.
Data Platform (R) - implementation, cache, SLA, observability.
Domain Owners (R) - Sources/Contracts.
Security/DPO (A/R) - privacy, access, audits.
SRE (R) - quotas, autoscale, incidents.
Finance (C) is the financial semantics of GGR/NGR/NET.

20) Implementation Roadmap

0-30 days (MVP)

1. Select 3-5 KPIs (GGR, deposits, retention D7).
2. Describe contracts and KPI semantics; Enable DQ/SLA.
3. Implement '/v1 'Query API + cache + mTLS/HMAC.
4. SLO dashboards (latency/success/freshness), audit/trace _ id.

30-90 days

1. Precompute popular storefronts, CDN cache.
2. Versioning '/v2 ', dual-read, migration guide.
3. Export APIs with signed uploads and WORMs.
4. Integration with BI/ML; quotas/tenants/geo-isolators.

3-6 months

1. Complete KPI taxonomy and widget library.
2. Smart tips/autocomplete filters, query linter.
3. Automatic Release Notes KPI, control of tolerances v1/v2.
4. External partner loop with restricted keys and RG policies.

21) Anti-patterns

Hidden KPI formula change without a new version and release notes.
Return PII/raw materials instead of aggregates/tokens.
The lack of cache/prerenders → expensive and slow.
Hard binding to a specific database (no layer abstraction).
Inconsistent TZ/FX → disparate numbers.

No rate limits/quotas → "DDOS own."

22) Templates (ready to use)

22. 1 SLO API Policy (snippet)

yaml api: analytics. v2 slo:
p95_latency_ms: 300 success_rate: 0. 995 freshness_sec_max: 900 quotas:
per_key_qps: 50 burst: 200 privacy:
min_group_size: 25 pii_in_response: false

22. 2 OpenAPI (snippet)

yaml paths:
/v2/metrics/revenue:
post:
requestBody:
content:
application/json:
schema: {$ref: '#/components/schemas/RevenueQuery'}
responses:
'200': {description: 'OK', content: {application/json: {schema: {$ref:'#/components/schemas/RevenueResponse'}}}}
'422': {description:'Privacy/Consent violation'}

22. 3 Release checklist

• KPI semantics updated and version upgraded
• Contract/schema in catalog; DQ/regression tests green
• Cache keys/TTL, prerenders configured
• Documentation and Sample Requests/Responses
• SLO and Quota Alerts Included
• RG/AML constraints tested

23) Related Sections

DataOps Practices, Audit and Versioning, Security and Encryption, Access Control, Data Tokenization, Retention Policies, Data Origin and Path, MLOps: Model Exploitation, Data Ethics.

Total

Analytics and metrics APIs are a contracted, secure and fast layer of access to gold data and KPIs. It guarantees uniform semantics, stable versions, default privacy and product-level performance - from internal dashboards to partner panels and ML.