Insights API · Referencia
La interfaz, al detalle.
Qué lleva una llamada a la HABLA™ Insights API, qué trae la respuesta, cómo llega un valor retenido y para qué cosas la interfaz nunca tuvo forma.
La interfaz, campo por campo. Autenticación, la forma de una solicitud y de una respuesta, cómo llega un valor retenido, el presupuesto de consultas, los errores y aquello que esta interfaz no tiene permitido devolver. Una institución puede exigir cada línea en un acuerdo, sección por sección.
Una interfaz que publica, no una interfaz que consulta
Una sola decisión da forma a todo lo que sigue, así que va primero. Esta interfaz publica lo que ya publica un informe: los mismos agregados, bajo los mismos umbrales, con la supresión ya aplicada y para quien ya podría verlos. Cada extremo que tiene sirve algo que un informe ya mostraría.
Una API es, por costumbre, una interfaz de consulta, y una interfaz de consulta sobre la actividad anónima es justo lo único que los documentos rectores de HABLA rechazan de plano. Así que la respuesta aquí es un conjunto publicado de opciones y no un motor de consultas con reglas alrededor. Quien llama elige de ese conjunto y recibe una respuesta que lleva su propia salvedad, y una institución puede exigir cada línea de eso en un acuerdo.
Autenticación
Una credencial decide qué puede leer quien llama, y quien llama no puede ampliarlo pidiéndolo.
- La organización va en la credencial, nunca en la solicitud
- Una credencial de organización queda ligada en el servidor a exactamente una organización. No hay ningún parámetro con el que nombrar una organización, así que no hay ningún parámetro que equivocar.
- Una credencial de referencia no puede nombrar ninguna
- El acceso a referencias nacionales es un servicio aparte, sin campo alguno para una organización en toda su interfaz. La separación es estructural porque un error de validación es la forma más probable de que una clase de acceso responda como la otra.
- Las llaves se guardan como resumen y se revocan una a una
- Una credencial solo puede almacenarse como resumen criptográfico, y se revoca por sí sola, sin tocar ninguna otra credencial de la misma institución.
- El registro anota la credencial, no la llave
- Toda llamada queda registrada y atribuida a un identificador de credencial. Ese registro es Configuración de Plataforma —un plano separado de la actividad anónima con la que se calculan las cifras— y no lleva ninguna identidad de las personas destinatarias.
La forma de una solicitud
Una solicitud es una elección entre opciones publicadas y no la descripción de una consulta. Hay tres cosas que se eligen y ninguna más.
- Un tema
- Una clave de tema del vocabulario publicado, y no una frase que redacte quien llama. El vocabulario es fijo, y una clave fuera de él no es una solicitud que la interfaz pueda expresar.
- Un periodo de reporte
- Uno de los periodos que un informe ya publica, nombrado por su etiqueta. Las fechas de inicio y fin no las elige quien llama, porque quien puede elegir la ventana puede elegir una segunda ventana que se diferencie de la primera en un solo día.
- Un segmento, de la lista publicada
- Para una referencia comparativa, uno de los segmentos declarados: sector, región y una banda de tamaño de organización. La tabulación cruzada libre está prohibida, porque así es como un segmento se estrecha hasta una sola organización sin que ningún filtro parezca sospechoso por separado.
Lo que no es un parámetro
- Un rango de fechas a elección de quien llama
- Una combinación libre de filtros
- Una unidad, un equipo, un turno o un departamento
- Un recuento mínimo, ni ningún umbral
- Una organización concreta, en una credencial de referencia
La forma de una respuesta
Una respuesta lleva consigo su propia interpretación, porque una cifra que viaja sin su salvedad se presentará sin ella. La salvedad viaja en el cuerpo y no en la documentación.
- El tema
- El tema del que habla la cifra, con las palabras del vocabulario publicado.
- Eventos de actividad
- El recuento, nombrado por lo que es. El campo se llama eventos de actividad y no actividad, porque una herramienta de reporte muestra el nombre del campo tal cual, y ningún conector estándar expone un objeto anidado junto a la serie que está graficando. La palabra honesta tiene que ser el encabezado de la columna.
- El estado
- Si la cifra es reportable o está retenida. Un solo valor, sin nada detrás: la sección siguiente explica por qué no hay un segundo valor que diga qué umbral se aplicó.
- Personas únicas: se desconoce
- Va como un valor en el cuerpo, no como prosa en un documento. HABLA cuenta eventos de actividad y no cuenta personas, así que el campo lo dice en lugar de omitirse y dejar que el lector lo suponga.
- Prevalencia: no medida
- Lo mismo, para la cifra que un lector estará más tentado de creer que tiene en la mano. La prevalencia no es algo que HABLA pueda calcular, y la respuesta lo dice en el mismo objeto que el recuento.
En esta página no aparece ningún cuerpo de ejemplo, y es deliberado. Una cifra de muestra es un número que un lector podría citar y que nadie podría verificar, y HABLA no imprime cifras que no pueda sostener. Los campos de arriba son ese cuerpo con los significados intactos y el número de muestra fuera.
Llevar la salvedad en el cuerpo es necesario y no suficiente. La otra mitad es contractual: las condiciones de la licencia exigirán que cualquier visualización de una cifra muestre a la vez su interpretación.
Cómo llega un valor retenido
Esta es la parte de la interfaz que leería primero quien intentara un ataque por diferencias, así que es la parte donde las reglas son más exactas.
- Ausente, o marcado como retenido
- Un valor por debajo de un umbral falta en la respuesta, o está presente y marcado como retenido. Esas son las dos formas, y no hay una tercera.
- La cifra real nunca se devuelve con una marca al lado
- La cifra real nunca viaja junto a un campo que diga que no debería mostrarse. Una marca que el cliente puede ignorar es un valor que el cliente publicará.
- El valor nunca se serializa como un cero
- Un valor retenido nunca se serializa como un cero. El cero es una cifra, se puede graficar, y es falsa.
- Un estado, sin razón detrás
- El estado es un único valor sin diferenciar. Una respuesta que explicara qué umbral se aplicó —población, actividad o una agregación— estrecharía el espacio de posibilidades restante para quien ataca por diferencias sin costarle nada, lo cual es peor trato que el de no saber por qué.
- La supresión ocurre antes de serializar
- Es una propiedad de lo que se construye y no de lo que se envía: las cifras que la interfaz puede alcanzar ya pasaron por la supresión, de modo que no hay ningún paso en el que un valor suprimido exista dentro de una respuesta y luego se quite.
El presupuesto, y para qué sirve en realidad
Hay un presupuesto de consultas, y es fácil venderlo por más de lo que es. Una versión temprana de este diseño lo hizo; la cuenta corregida es la de abajo.
Los umbrales y el tope de participación son propiedades del momento de construcción: acotan lo que puede divulgarse sin importar cuántas consultas permitidas emitan cuantas partes sea. El presupuesto es un control del momento de servicio, y su trabajo es más estrecho: acota la escala de la enumeración automatizada. Una persona haciendo clic en una consola podría, en principio, enumerar celdas y resolver por resta, pero no al volumen que hace falta para construir un sistema de ecuaciones útil. Un script sí, y para eso está el presupuesto.
- Cuenta combinaciones resolubles, no repeticiones
- La secuencia peligrosa es un conjunto de llamadas legítimamente distintas —distintos segmentos, distintos periodos, cada una permitida— cuyas diferencias triangulan un valor retenido. Rechazar repeticiones casi idénticas no toca eso, así que el presupuesto sigue las combinaciones y no las repeticiones.
- Se acumula contra la institución, no contra la llave
- Un presupuesto por credencial se vence teniendo varias: un cliente grande con llaves por departamento, o una organización de investigación y la institución que la patrocina, reparten las llamadas para que ningún presupuesto salte y luego reconcilian las respuestas fuera de línea. El presupuesto se acumula contra el cliente legal.
- Volver a consultar es gratis; una celda nueva no
- Un proceso de reporte que vuelve a pedir un periodo que no ha cambiado no cuesta nada, y una celda genuinamente nueva sí cuenta. Sin esa distinción, un presupuesto o no frena el abuso o rompe toda integración legítima el primer día.
No se publica ninguna cifra para nada de esto, y la ausencia es deliberada. Un número de presupuesto significa algo solo cuando se ha calibrado contra el tráfico que gobierna; un número publicado antes de eso es uno con el que un cliente haría planes y que HABLA no podría defender.
Errores
Lo que restringe una respuesta de error no es su código. Es la regla de abajo, que cumple todo error: un error puede ayudar a corregir la llamada, y nunca puede decir nada sobre una cifra.
- Un error puede decir qué puede hacerse distinto
- Una clave de tema desconocida, un periodo que no está publicado, un segmento fuera de la lista declarada, una credencial revocada o agotada: cada uno de ellos tiene respuesta, porque ninguno dice nada sobre una cifra.
- Un error no puede decir por qué se retuvo un valor
- La retención se comunica como un estado de la cifra y nunca como un error que lleve una razón. La regla del valor único sin diferenciar de arriba es todo el argumento, y el canal de errores es el sitio obvio por donde se filtraría.
- Rechazar una llamada tampoco filtra nada
- Una llamada rechazada por presupuesto dice que se rechazó por presupuesto. No dice cuál de las llamadas anteriores hizo resoluble a esta, porque eso es la misma divulgación en otro campo.
Aquello para lo que esta interfaz nunca tuvo forma
Esto no son rutas que existen y devuelven un error. No son formas que el diseño tenga, que es una afirmación distinta y más fuerte. La actividad anónima que hay debajo de una cifra es lo que ninguna de ellas podría alcanzar: la interfaz lee la salida ya suprimida del motor de informes y no tiene conexión propia con nada más.
- Ningún extremo para datos anónimos en bruto o por evento
- Ningún extremo que lleve de un tema a las personas que lo eligieron
- Ningún extremo que diga qué organizaciones contribuyeron, ni que las ordene
- Ningún extremo que devuelva una cifra por debajo de un umbral, en ninguna forma, ni su existencia
- Ningún parámetro, en ningún sitio, que rebaje un umbral
La regla a la que se reduce toda la interfaz: un extremo que devolviera algo que un informe no mostraría no es un extremo que esta interfaz tenga.
Póngala en el acuerdo
Esta página está escrita tanto para quien vaya a firmar una integración como para quien vaya a escribirla. Sirve para decidir si esta es una interfaz contra la que vale la pena construir, y para exigir, en un acuerdo, que se comporte como dice esta página.
Solicite un recorrido guiadoLo que una institución necesita saber