API REST — parámetros de ruta

Todos los endpoints REST de Personyze comparten una sintaxis común de parámetros de ruta para filtrar, proyectar columnas, ordenar y limitar resultados. Los mismos modificadores — where, columns, column, order_by, order_by_desc, limit — funcionan igual en todos los objetos, con una forma abreviada para las búsquedas por clave primaria.

Requisitos previos: Descripción general de la API REST y Autenticación — ahí se explican la forma de la URL y las credenciales.

Forma general de la URL

Después del nombre del objeto, la ruta de la URL es una secuencia de pares /<modifier>/<value>/... así:

/rest/<object>/[<id>|]<modifier>/<value>/<modifier>/<value>/...

Notas:

• El orden no importa. /limit/100/where/x=y equivale a /where/x=y/limit/100.
• Cada modificador aparece como máximo una vez por solicitud. Varias condiciones where van dentro de un único segmento where/ usando los operadores & y | (consulte más abajo).
• Los valores se decodifican como URL antes de analizarlos — así que un valor de columna que contenga /, =, &, o % debe codificarse con porcentajes.

Forma de un solo id (búsqueda por clave primaria)

Un segmento numérico sin más en la primera posición es una búsqueda por clave primaria:

GET /rest/<object>/<id>

Devuelve un registro (un objeto, no un array de un elemento), o 400 Row not found si el ID no existe.

GET /rest/placeholders/14
GET /rest/users/57291                    # PK = user_id

Para búsquedas por identificador externo (su SKU, su ID del CRM, etc.), use la forma where con internal_id:

GET /rest/users/where/internal_id=42
GET /rest/products/where/internal_id=SKU-1234

where — filtrar

Filtra el conjunto de resultados. La forma más simple es where/<column><op><value>:

Combinar condiciones con & (AND) y | (OR)

where/<cond1>&<cond2>          # both must match (AND)
where/<cond1>|<cond2>          # either matches (OR)
where/<a>&<b>|<c>&<d>          # (a AND b) OR (c AND d) — & binds tighter than |

Ejemplos:

where/status=active&age_from>=18
where/email=alice@example.com|email=bob@example.com
where/category:books,tools&is_in_stock=yes

Requisito de columna indexada

Los endpoints REST que envuelven tablas grandes (users, events, sessions_archive, summary_actions, etc.) rechazan las consultas cuya cláusula where o order_by no aprovecha un índice. El mensaje de error nombra las columnas indexadas que expone el endpoint:

Cannot do this operation on whole table: column "uset_id" is not indexed.
Please, use "where" condition or order by an indexed column
(user_id, last_session_time, data_last_modified, fb_id, email, internal_id).

Los índices compuestos aparecen con la forma [col1, col2, col3] . Solo la columna inicial de un índice compuesto se puede usar como filtro de una sola columna:

... or order by an indexed column
(user_id, [product_internal_id, user_id, transaction_time], status, time).

Aquí, where/product_internal_id=... aprovecha el índice compuesto, pero where/transaction_time>... por sí solo no — es la tercera columna del índice compuesto, útil solo en combinación con product_internal_id y user_id.

columns — proyectar columnas concretas

Restringe las columnas proyectadas. Lista separada por comas. Por defecto, «todas las columnas documentadas» del objeto.

GET /rest/users/where/internal_id=42/columns/user_id,first_name,last_name

Columnas desconocidas: en los objetos que admiten nombres de columna dinámicos (users, articles, products), las columnas desconocidas se devuelven como null. En los objetos con esquema fijo, obtendrá 400 Unknown column.

column (singular) — array plano de valores

Abreviatura de «seleccionar una columna y devolver un array plano de valores» en lugar de un array de objetos.

GET /rest/users/where/last_session_time>1700000000/column/email
→ ["alice@example.com", "bob@example.com", ...]

Frente a la forma columns en plural:

GET /rest/users/where/last_session_time>1700000000/columns/email
→ [{"email":"alice@example.com"}, {"email":"bob@example.com"}, ...]

Útil cuando quiere pasar el resultado directamente a otro sistema que espera una lista (p. ej. al crear una exportación de audiencia o al eliminar direcciones de email duplicadas).

order_by / order_by_desc

order_by/<col>[,<col>...]          # ascending
order_by_desc/<col>[,<col>...]     # descending

Varias columnas: los empates en la primera columna se resuelven con la segunda, y así sucesivamente. Cada dirección (order_by o order_by_desc) se aplica a todas las columnas indicadas.

GET /rest/users/order_by_desc/last_session_time/limit/100

La primera columna indicada debe ser una columna indexada (o la columna inicial de un índice compuesto) cuando no hay una cláusula where — de lo contrario, el endpoint rechaza la solicitud por ser un recorrido de tabla completa.

limit — paginación

limit/<count>                      # first <count> rows
limit/<offset>,<count>             # skip <offset> then take <count>

El tope es de 1.000 filas por solicitud. Los valores mayores se rechazan con 400 Only can select up to 1000 rows.

GET /rest/users/order_by_desc/last_session_time/limit/100
GET /rest/users/order_by_desc/last_session_time/limit/100,100   # rows 100..199

Paginación por cursor — la opción preferida para conjuntos de resultados grandes

Los valores altos de offset se vuelven lentos porque la base de datos tiene que volver a leer todas las filas omitidas. Para conjuntos de resultados más grandes, pagine recorriendo la columna indexada de order_by con condiciones de tipo cursor where:

# page 1
GET /rest/users/order_by_desc/last_session_time/limit/1000

# page 2 — pass the last seen value
GET /rest/users/where/last_session_time<1730000000/order_by_desc/last_session_time/limit/1000

# page 3 — pass the last seen value from page 2
GET /rest/users/where/last_session_time<1729000000/order_by_desc/last_session_time/limit/1000

El valor del cursor es el que tenía el último registro de la página anterior en la columna indexada. Así sigue siendo rápido indefinidamente — cada página es un recorrido de rango indexado, no un recorrido lineal de «saltar 50.000 filas».

Todo junto

GET /rest/products
        /where/category=tools&is_in_stock=yes
        /columns/id,internal_id,title,price,inventory
        /order_by/title
        /limit/100

(Saltos de línea añadidos para facilitar la lectura — en realidad va todo en una sola línea, sin espacios.)

Próximos pasos