Consultar con filtros y paginación

Los objetos de una colección se piden en {api-root}/collections/{id}/objects/, y la norma define filtros en la dirección: added_after, limit, next y los match[...] (match[id], match[type], match[version], match[spec_version]). Varios valores dentro del mismo match se combinan con O; filtros distintos, con Y.

El filtro que más se malinterpreta es added_after. La especificación dice que filtra por el momento en que el servidor agregó el objeto a la colección, y que no tiene relación alguna con las fechas que el objeto STIX lleva dentro (created, modified, valid_from). Un indicador escrito en octubre que la curaduría sube hoy entra en una consulta de «lo agregado desde ayer».

Abre manifiesto-col-sal-11.json. El manifiesto lista, para cada objeto, su id, su date_added (cuándo lo agregó el servidor), su version y su media_type, sin traer el objeto entero.

Cuando un objeto STIX tiene modified, esa propiedad es su versión. El manifiesto permite comparar, objeto por objeto, cuándo se escribió esa versión y cuándo la agregó el servidor. Si los separan semanas, el objeto llega «nuevo» a tu sondeo aunque el emisor lo escribiera hace tiempo, y quien filtra por las fechas internas lo deja fuera sin darse cuenta.

Abre respuesta-r1.json y respuesta-r2.json (lo que devolvió el sondeo) y crúzalos con el manifiesto.

Una respuesta de objetos llega en un sobre con objects, more y next. Si more es true hay más páginas, y next es un valor opaco que el cliente devuelve para pedir la siguiente. La norma pide usar next con las mismas opciones de la consulta original: el valor señala una posición dentro de esa búsqueda concreta, y mezclarlo con otros filtros no tiene sentido.

Abre registro-del-cliente.log. Cada petición lleva un número (R-1, R-2...) y su respuesta va en la línea siguiente.

Las respuestas de objetos y de manifiesto llevan dos cabeceras: X-TAXII-Date-Added-First y X-TAXII-Date-Added-Last, la primera y la última fecha de agregado de lo que trae. La norma prevé usar la segunda como added_after cuando el servidor dice que hay más pero no da next, y es también la marca natural para que el sondeo del día siguiente pida solo lo que se agregó después de lo último que ya recibiste. Tomar la hora del reloj del cliente, en cambio, abre huecos si los relojes no coinciden.

En el registro, el sondeo de las 06:00 terminó en dos páginas.

limit es un máximo que pide el cliente, no una promesa del servidor: la especificación permite que devuelva menos objetos de los pedidos, y nunca más. Lo que dice si queda contenido es more. Un cliente que se fía del número recibido para decidir si terminó pierde objetos en silencio.

Lee en el registro la petición R-4 y la nota del cliente.