Interfaces de dados

1) Por que uma interface elaborada

Velocidade e previsibilidade: as métricas de negócios e relatórios são colocados em SLA, sem «descarregamentos manuais».
Segurança e privacidade: PII/biometria sob controle, k-anonimato, geo-fronteiras.
Flexibilidade: clientes diferentes (BI, serviços, parceiros, DS/ML) recebem exatamente o que precisam.
Reutilizar: «dados como produto» com contratos e versões.

2) Mapa de interfaces (quando)

SQL/ANSI + dialetos vendedores: analista interativo, BI, ad-line.
REST JSON: unidades estáveis e dados operacionais, integração com parceiros.
GraphQL: leitura «seletiva» flexível e gráfico de navegação (medidas/fatos).
gRPC (protobuf): baixa latência online-serving (Função Store).
Arrow Flight/Parquet over HTTP/S3-presented: dampas de coluna rápida para DS/ML.
OData: ferramentas enterprise, modelo «tabela como serviço».
Streams (Kafka/Pulsar) + CDC/Webhooks: eventos em tempo real, integração a jato.
Federation (Trino/Pró): um único ponto de entrada para várias fontes.

Regra: unidades e cortes estáveis → REST/MV, ricas solicitações aleatórias → SQL, baixa latência/fichas online → gRPC, forma flexível de resposta → GraphQL, troca binária em massa → Arrow/Parquet.

3) Contratos e versões (semver)

`MAJOR. MINOR. PATCH 'para cada API/esquema/evento.
MAJOR: alterações incompatíveis (novo caminho/topic/tabela).
MENOR: adições compatíveis de campos/argumentos.
PATCH: editar descrições/limites.
Os contratos registram esquema, filtros, limites, privacidade, SLO.

yaml openapi: "3. 0. 3"
info: {title: "Analytics API", version: "2. 4. 0"}
paths:
/v2/payments/metrics:
get:
parameters:
- {name: brand, in: query, schema: {type: string}, required: true}
- {name: country, in: query, schema: {type: string}}
- {name: from, in: query, schema: {type: string, format: date-time}}
- {name: to, in: query, schema: {type: string, format: date-time}}
- {name: group_by, in: query, schema: {type: string, enum: [psp,status,day]}}
- {name: limit, in: query, schema: {type: integer, default: 500}}
responses:
"200": {description: "OK"}
x-slo: {p95_latency_ms: 1200, freshness_max: "PT5M"}
x-privacy: {pii: false, min_group_size: 20}

4) Acesso ao analista (SQL e federação)

Um gateway SQL com rol/máscaras (row/column-level security).
Aquelas projeções sob BI: nomes estáveis e semântica; os pedidos de heavy são feitos para pré-agremiações.
Federation (Trino/Presto): um único ponto de entrada, mas com políticas: quais diretórios e quais funções estão disponíveis.
Lakehouse (Iceberg/Delta/Hudi): time-travel, extração snapshot via SQL/REST.
Квоты: scanned bytes/query, concurrency, wall-time.

5) GraphQL (forma flexível)

Damos ao cliente para montar o campo adequado, mas executamos acima de vozes/projeções preparadas, com limites de profundidade/ossos.

graphql type Query {
payments(
brand: String!, country: String, from: DateTime!, to: DateTime!,
first: Int = 200, after: String
): PaymentConnection
}

Políticas: depth-5, total nodes 5k, proibindo regex/like aleatórios em linhas; Acenamos com frequência.

6) gRPC/Função Store (baixa latência)

Fici online para antifrode/recomendação/RG.

proto service FeatureStore {
rpc GetFeatures (FeatureRequest) returns (FeatureResponse);
}
message FeatureRequest { string user_tok = 1; repeated string features = 2; }
message FeatureResponse { map<string, FeatureValue> values = 1; int64 ts_micros = 2; }

Requisitos: p95 ≤ 50-100 ms, coerência exata de offlayn↔onlayn, TTL fic, dinheiro LRU, idempotency e mTLS.

7) Fluxos e CDC

Eventos de domínio: 'payments. deposit_accepted`, `game. round_finished`.
CDC (de OLTP): alteração de status/limite em near-real-time.
Webhooks para parceiros: subscrição de agregados (por exemplo, «falhas PSP> limiar»).
Políticas de retrações/confirmação: exactly-once para críticos, at-least-once para monitoramento.

8) Lagos e grandes amostras

Arrow Flight para descarregamentos rápidos de coluna em DS/ML.
URL presented no Parquet/Feather, com TTL curto e pedido assinado.
Chunked transfer e controlar o tamanho do arquivo; registro de downloads (auditoria WORM).

9) Filtros, paginação, triagem

A paginação Keyset (cursor) em vez do OFFSET para conjuntos maiores.
Filtros: whitelists por campos, tipos e operadores ('=, IN, BETWEEN, prefix').
Triagem: lista limitada de campos, ordem default.
Partial response: 'fields = brand, country, amount' reduz a carga útil.

http
GET /v2/game-rounds? brand=X&from=...&to=...&first=1000&after=eyJkYXRlIjoi...

10) Em dinheiro e custo

Result cache para solicitações de modelo, deficiente por token de frescura (snapshot id).
Edge-dinheiro/CDN para unidades públicas/semiduráveis (sem PII).

Parâmetros Budet: limite de scanned bytes, tempo de consulta, quotas rps/min

Priorizar pool: 'bi _ hot', 'adhoc', 'parceiro _ api'.

11) Segurança e privacidade

AuthN: OAuth2/OIDC (cliente credentals para serviços, PKCE para pessoas).
AuthZ: RBAC + ABAC (atributos: marca, país, licença, papel).
mTLS entre serviços, TLS 1. 2 + para fora.
Higiene PII: máscaras/tocenização em uma camada de API, máscaras invertebradas, máquinas k-anonimato.
Geo/tenant-isolamento: rotação de solicitações para a região da licença; chaves de criptografia para marca/região.
DSAR/Legal Hold: pesquisa por tocador, segredos para congelar conjuntos.

12) Observabilidade (SLI/SLO) e proteção

SLI: p50/p95/p99 lat, error-rate, rps, bytes scanned, cache hit, quotas/limites, proporção de colunas mascaradas, proporção de falhas de autorização.
SLO: p95 latência, dados frescos,% de pedidos de sucesso, min-group-size nas respostas.
Alerts: Crescimento scanned bytes, queda do hit-rate, pico 429/5xx, tentativas de acesso ao PII, fugas de cursores.

yaml slo:
p95_latency_ms: 1200 success_rate: 0. 995 freshness_max: "PT5M"
privacy:
pii_allowed: false min_group_size: 20 quotas:
rps: 50 max_scanned_mb: 256

13) Formatos e compressão

JSON para compatibilidade; O CSV é apenas para pequenas e simples exportações.
Parquet/Arrow - padrão para grandes descarregamentos.
Compressão: gzip/zstd (negociações através de 'Accept-Encoding').
Content-negotiation: `Accept: application/x-parquet`.

14) Métricas como API (Analytics/OLAP-Passarela)

Métricas de nível superior: GGR/NET, CR, retenção, incidentes RG - como recursos com os parâmetros 'brand, country, window, group _ by'.
Approx (HLL/TDigest) для distinct/percentiles.
A caixa com a chave é '(metric, params, snapshot _ id)'.

15) Especificidades iGaming - endpoints prontos

'GET/v2/payments/metrics' - falhas/uprouvs por PSP/país/marca com 7/30d janelas.
'GET/v2/game-rounds/metrics' - top games/provedores, p95 duração, janelas RTP.
'GET/v2/rg/cases' - limitações ativas/auto-exclusão (unidades k-anônimas).
'POST/v1/featuras: get' (gRPC) - Fici on-line para compilação de from/recompensador.
'POST/v1/webhooks/psp-alerts' - notificações 'decline rate> limiar'.

16) Exemplos de contratos

graphql query {
payments(brand:"X", country:"TR", from:"2025-10-01", to:"2025-10-31", first:500) {
edges { node { day totalAmount declines psp } cursor }
pageInfo { hasNextPage endCursor }
}
}

json
{"event_id":"...","occurred_at":169..., "brand":"X","psp":"Papara","status":"declined","amount":"100. 00","currency":"TRY"}

/flight/v1/query? dataset=gold. payments&from=...&to=...&brand=X&format=arrow

17) Processo de publicação de uma nova interface

1. ADR: problema/valor/clientes/segurança/custo.
2. Contrato: esquema, filtros, limites, privacidade, SLO, versões.
3. Simulação de carga: top-N consultas, p95/scan-bytes, valor.
4. Validação/kesh/quotas: incluir padrão.
5. Documentação e SDK: exemplos, limites, erros, retraias, idempotidade.
6. Canary:% dos clientes, testes de regressão, alertas.
7. GA: versão no catálogo Data Products, relatório de efeitos.

18) Anti-pattern

Abrir SQL «cru» a todos - vazamentos PII, custo imprevisível.
A paginação OFFSET e 'SELECT' são dores de latência e conta.
GraphQL sem limites de profundidade/custo.
O REST que devolve demais colunas sem 'fields =...'.
Falta de k-anonimato e min-group-size nas unidades.
Cota/limite zero e dinheiro desativado.
Sem versionagem/contratos - «quebrar» clientes a cada mudança.
A mesma interface para todos os países/marcas é ignorar as regras regionais.

19) Mapa de trânsito de implementação

0-30 dias (MVP)

1. O catálogo Data Products (métricas/cortes) e seus contratos OpenAPI/GraphQL.
2. SQL-gateway com RLS/CLS, KK-anonimato de unidades, quotas básicas.
3. Um REST de endpoint ('/payments/metrics') + dinheiro + pool 'bi _ hot/adhoc'.
4. gRPC Função Store: leitura de 10-20 principais fichas online (p95 ≤ 80 ms).

30 a 90 dias

1. Interfaces strim (Kafka/Webhook) para eventos PSP/jogos.
2. Arrow/Parquet descarregar com um URL postado; O catálogo de snapshots.
3. A cabana de federação (Trino/Pró) com políticas explícitas.
4. Observabilidade: dashboard SLI/SLO, alertas para custo/latência/PII.

3-6 meses

1. SDK (TypeScript/Python/Go) com retais/idumpotência/quotas.
2. Finos GraphQL cortes para produtos e parceiros.
3. Alongamento de gRPC/FS, alinhamento de offlayn↔onlayn; shadow→canary lançamentos.
4. Auditoria de privacidade/DSAR; relatórios de complacência de acessibilidade.

20) RACI

Data Platford (R): gateway, dinheiro, quotas, federação, observabilidade.
Data Governance (A/R): contratos, versões, privacidade/k-anonimato.
Domain Owners (R): semântica de campos, invariantes de negócios, Data Products.
Segurança/DPO (A/R): AuthN/Z, geo-isolamento, DSAR/Legal Hold.
SRE/Observabilidade (C): SLO/SLI, alertas, capacity.
Analytics/BI/DS (C): requisitos de formulário/unidade, SDK.

21) Seções relacionadas

Indexação de armazenamento analítico, Otimização de consultas analíticas, Circuitos de dados e sua evolução, Validação de dados, Práticas de Lidar, API Analistas e Métricas, Função Store, Segurança de Dados e Criptografia, Controle de Acesso, Políticas de Armazenamento de Dados.

Resultado

Interfaces de acesso de dados bem projetadas transformam armazenamento e fluxo em um produto confiável, como SLA previsível, custo controlado, privacidade e linguagem unificada para os comandos do produto, analistas, complacentes e parceiros. Em iGaming, isso significa capturar mais rapidamente as falhas do PSP, compreender o comportamento dos jogadores e cumprir as exigências dos reguladores - sem descarregamentos manuais ou migrações noturnas.