Interfaces de acceso a datos

1) Por qué una interfaz pensada

Velocidad y previsibilidad: las métricas de negocio y los informes se ajustan al SLA, sin «descargas manuales».
Seguridad y privacidad: PII/biometría bajo control, k-anonimato, geo-fronteras.
Flexibilidad: diferentes clientes (BI, servicios, socios, DS/ML) obtienen exactamente lo que necesitan.
Reutilización: «datos como producto» con contratos y versiones.

2) Mapa de interfaces (cuando qué)

SQL/ANSI + dialectos vendores: análisis interactivo, BI, ad-hoc.
NAT JSON: unidades estables y datos operativos, integraciones con socios.
GraphQL: lectura flexible «selectiva» y gráfico de navegación (medidas/hechos).
gRPC (protobuf): baja latencia de serving en línea (Feature Store, scoring).
Flight/Parquet over HTTP/S3-presigned: «volcado» de columna rápida para DS/ML.
OData: herramientas empresariales, modelo «tabla como servicio».
Streams (Kafka/Pulsar) + CDC/Webhooks: eventos en tiempo real, integraciones reactivas.
Federación (Trino/Presto): punto de entrada único a múltiples fuentes.

Regla: agregados y cortes estables → NAT/MV, ricas solicitudes arbitrarias → SQL, baja latencia/fiches en línea → gRPC, forma de respuesta flexible → GraphQL, intercambio binario masivo → Arrow/Parquet.

3) Contratos y versiones (semver)

`MAJOR. MINOR. PATCH 'para cada API/esquema/evento.
MAYOR: cambios incompatibles (nueva ruta/topic/tabla).
MENOR: adiciones compatibles de campos/argumentos.
PATCH: editar descripciones/límites.
Los contratos fijan: esquema, filtros, límites, privacidad, 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) Acceso a análisis (SQL y federación)

Puerta de enlace SQL con roles/máscaras (row/column-level security).
Viuches/proyecciones bajo BI: nombres estables y semántica; las solicitudes heavy salen en preagregación.
Federación (Trino/Presto): un único punto de entrada, pero con políticas: qué directorios y qué funciones están disponibles.
Lakehouse (Iceberg/Delta/Hudi): tiempo-viaje, snapshot-extracción a través de SQL/NAT.
Квоты: scanned bytes/query, concurrency, wall-time.

5) GraphQL (forma flexible)

Damos al cliente ensamblar el campo deseado, pero ejecutamos encima de las pinzas/proyecciones preparadas, con límites de profundidad/huesos.

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, prohibimos el regex/like arbitrario en líneas; caché consultas frecuentes.

6) gRPC/Feature Store (baja latencia)

Fiches online para la puntuación antifraude/recomendaciones/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, consistencia exacta de offlayn↔onlayn, TTL fich, caché LRU, idempotency y mTLS.

7) Flujos y CDC

Eventos de dominio: 'payments. deposit_accepted`, `game. round_finished`.
CDC (desde OLTP): cambios en los estados/límites en tiempo near-real.
Webhooks para socios: suscripción a agregados (por ejemplo, «fallas PSP> umbral»).
Políticas de retroceso/confirmación: exactly-once para crítico, at-least-once para monitoreo.

8) Lagos y grandes muestras

Flight Arrow para descargas de columna rápidas en DS/ML.
URL preconstruida en Parquet/Feather, con TTL corto y solicitud firmada.
Transferencia chunked y control de tamaño de archivo; registro de descargas (auditoría WORM).

9) Filtros, paginación, clasificaciones

Keyset-paginación (cursor) en lugar de OFFSET para conjuntos grandes.
Filtros: whitelists por campos, tipos y operadores ('=, IN, BETWEEN, prefix').
Ordenar: lista limitada de campos, orden predeterminado.
Respuesta parcial: 'fields = brand, country, amount' reduce la carga útil.

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

10) Almacenamiento en caché y costo

Resultado cache para consultas de plantillas, inhabilitado para el token de frescura (snapshot id).
Edge caché/CDN para agregados públicos/semipublicados (sin PII).
Parámetros de budget: límite de bytes escaneados, tiempo de espera de consulta, cuotas de rps/min.
Priorizar grupos: 'bi _ hot', 'adhoc', 'partner _ api'.

11) Seguridad y privacidad

AuthN: OAuth2/OIDC (clientes credentials para servicios, PKCE para personas).
AuthZ: RBAC + ABAC (atributos: marca, país, licencia, rol).
mTLS entre servicios, TLS 1. 2 + hacia afuera.
Higiene PII: máscaras/tokenización en la capa API, máscaras de columna, unidades k-anonimato.
Geo/tenant-aislamiento: enrutamiento de solicitudes a la región de licencia; claves de cifrado por marca/región.
DSAR/Legal Hold: búsqueda por token de sujeto, secretos para congelar conjuntos.

12) Observabilidad (SLI/SLO) y protección

SLI: p50/p95/p99 lat, error-rate, rps, bytes scanned, cache hit, cuotas/límites, proporción de columnas enmascaradas, porcentaje de denegaciones de autorización.
SLO: p95 latencia, frescura de datos,% de consultas exitosas, min-group-size en las respuestas.
Alertas: crecimiento de bytes escaneados, caída de hit-rate, ráfaga de 429/5xx, intentos de acceso a 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 y compresión

JSON para compatibilidad; CSV - sólo para exportaciones pequeñas y sencillas.
Aparquet/Arrow - Por defecto para descargas grandes.
Compresión: gzip/zstd (negociación a través de 'Accept-Encoding').
Content-negotiation: `Accept: application/x-parquet`.

14) Métricas como API (Analytics/puerta de enlace OLAP)

Métricas de nivel superior: GGR/NET, CR, retención, incidentes RG - como recursos con los parámetros 'brand, country, window, group _ by'.
Approx (HLL/TDigest) для distinct/percentiles.
Caché con clave: '(metric, params, snapshot_id)'.

15) Especificidad de iGaming - Endpoints terminados

'GET/v2/payments/metrics' - fallas/apruvas por PSP/país/marca con ventanas 7/30d.
'GET/v2/game-rounds/metrics' son los mejores juegos/proveedores, p95 de duración, ventanas RTP.
'GET/v2/rg/cases' - restricciones/autoexclusiones activas (unidades k-anónimas).
'POST/v1/features: get' (gRPC) es un fiche online de puntuación frod/recommender.
'POST/v1/webhooks/psp-alerts' - notificaciones de 'nota de decisión> umbral'.

16) Ejemplos 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) Proceso de publicación de la nueva interfaz

1. ADR: problema/valor/clientes/seguridad/costo.
2. Contrato: esquema, filtros, límites, privacidad, SLO, versiones.
3. Modelado de carga: consultas superiores a N, p95/bytes escaneados, costo.
4. Validación/caché/cuotas: habilitar por defecto.
5. Documentación y SDK: ejemplos, límites, errores, retraídas, idempotencia.
6. Canario:% de clientes, pruebas de regresión, alertas.
7. GA: versión en el directorio Data Products, informe de efectos.

18) Anti-patrones

Abrir el SQL «crudo» a todos - filtraciones PII, costo impredecible.
La paginación OFFSET y 'SELECT' son dolor por latencia y factura.
GraphQL sin límites de profundidad/costo.
NAT, que devuelve demasiadas columnas sin 'fields =...'.
Ausencia de k-anonimato y min-group-size en las unidades.
Cuotas/límites cero y caché deshabilitada.
No hay versionados/contratos - «rompemos» los clientes cada vez que se cambia.
La misma interfaz para todos los países/marcas: ignora las reglas regionales.

19) Hoja de ruta para la aplicación

0-30 días (MVP)

1. Catálogo de productos de datos (métricas/cortes) y sus contratos OpenAPI/GraphQL.
2. Puerta de enlace SQL con RLS/CLS, anonimato k de agregados, cuotas base.
3. Un Endpoint Métrico de NAT ('/payments/metrics ') + caché + pools' bi _ hot/adhoc '.
4. gRPC Feature Store: lectura de 10-20 fichas clave en línea (p95 ≤ 80 ms).

30-90 días

1. Interfaces de streaming (Kafka/Webhook) para alertas PSP/eventos de juegos.
2. Arrow/Parquet de descarga con URL preconstruida; Catálogo de snapshots.
3. Puerta de enlace de federación (Trino/Presto) con políticas explícitas.
4. Observabilidad: dashboard SLI/SLO, alertas por costo/latencia/PII.

3-6 meses

1. SDK (TypeScript/Python/Go) con retrés/idempotencia/cuotas.
2. Finos cortes GraphQL para productos y socios.
3. Ampliación de gRPC/FS, negociación de offlayn↔onlayn; shadow→canary lanzamientos.
4. Auditoría de privacidad/DSAR; informes de cumplimiento de acceso.

20) RACI

Plataforma de datos (R): puertas de enlace, caché, cuotas, federación, observabilidad.
Data Governance (A/R): contratos, versiones, privacidad/k-anonimato.
Domain Owners (R): semántica de campos, invariantes de negocios, productos de datos.
Seguridad/DPO (A/R): AuthN/Z, aislamiento geo, DSAR/Legal Hold.
SRE/Observabilidad (C): SLO/SLI, alertas, capacidad.
Analytics/BI/DS (C): requisitos para formularios/agregados, SDK.

21) Secciones relacionadas

Indexación de almacenamiento analítico, Optimización de consultas analíticas, Esquemas de datos y su evolución, Validación de datos, Prácticas de DataOps, API de análisis y métricas, Feature Store, Seguridad de datos y cifrado, Control de acceso, Políticas de retención de datos.

Resultado

Las interfaces de acceso a datos correctamente diseñadas convierten el almacenamiento y los flujos en un «producto» confiable: SLAs predecibles, costo controlado, respeto a la privacidad y lenguaje único para equipos de productos, análisis, cumplimiento y socios. En iGaming, esto significa atrapar fallas PSP más rápido, entender el comportamiento de los jugadores y cumplir con los requisitos de los reguladores - sin descargas manuales y migraciones nocturnas.