Mecanismos de filtrado, ordenamiento, paginación y selección de propiedades

Como se ha definido hasta el momento, solamente existe un endpoint que retorna listado de los recursos y es el método GET. Por lo tanto, es necesario enviar más información en el "Querystring" de la petición al recurso, que permita implementar filtros, ordenamiento, paginación y/o selección de propiedades.

Importante
Con el fin de crear un entorno flexible y altamente configurable para fines de las consultas, se expone un modelo con GraphQL. Este es un endpoint único para todo el API, y está documentado más adelante en este mismo documento. Con esta herramienta se pueden escribir querys al API a través de una sintaxis propia

Sin embargo, es importante implementar algunos mecanismos de filtrado, ordenamiento y paginación para el endpoint GET de cada recurso, de tal forma que puedan utilizarse ambos mecanismos.

En tal sentido, se implementarán las siguientes características:

Filtrado

Para las consultas más comunes, se puede implementar enviando un valor fijo para cada propiedad que queremos que le aplique un filtro. Por ejemplo:

GET /incapacidades?estado=Autorizado&codigoPeriodoPlanilla=2023

Así, de una manera simple, se pueden obtener los listados de entidades que sean de uso más común. Mas adelante para cada endpoint, se documentará si existe esta posibilidad y que propiedades filtro se van a soportar.

Ordenamiento

Se debe permitir especificar el orden ascendente o descendente en que se desean obtener los datos requeridos, cuando estos retornan una lista de elementos. Por ejemplo:

GET /incapacidades?sort=-fechaFin,+codigoTipoIncapacidad

El signo más y el signo menos sirven para especificar si el orden será ascendente o descendente, el signo más sería opcional y si no se especifica se asume un orden ascendente.

Paginación

Un API no puede retornar un número infinito de registros, porque no se podría controlar el tráfico. Para ello en toda petición se debe poder especificar el número máximo de registros y el registro de inicio (limit y offset, respectivamente). Por ejemplo:

GET /incapacidades?page=5&pagesize=10

Eso permitiría que el API retorne del registro número 50 hasta el 59 o hasta el número de registros que encuentre, si solo quedan 5 registros, pues retornará del 50 al 54. Por defecto hay que establecer un máximo de 100 registros por petición. Para que esto funcione bien, la estructura de datos que retorna este recurso, además de un arreglo de entidades, va a retornar la siguiente información:

  • Número Total de registros existentes, luego de aplicar los filtros.
  • Número de página (page) al que corresponde el arreglo de entidades.
  • Número de registros (pagesize) que se retornan en el arreglo de entidades.
  • Enlace para obtener la siguiente página.
  • Enlace para obtener la página previa.
  • Enlace para obtener la primera página.
  • Enlace para obtener la última página.

Por ejemplo, la respuesta del ejemplo anterior, al requerir la página 3 será similar a esto:

{
  "total": "55",
  "page": 3,
  "pagesize": 10,
  "top": "/incapacidades?page=0&pagesize=10",
  "last": "/incapacidades?page=5&pagesize=10",
  "prev": "/incapacidades?page=2&pagesize=10",
  "next": "/incapacidades?page=4&pagesize=10",
  "recs": [
    {
        "id": 453,
        "codigoTipoIncapacidad": 2,
        . . .
    },
    {
        "id": 459,
        "codigoTipoIncapacidad": 1,
        . . .
    },
    . . .
  ]
}

Selección de propiedades

Debería ser posible especificar cuáles propiedades del recurso se desea obtener al realizar una búsqueda. Para ello se dispondrá de un parámetro que especifique una lista de propiedades separadas por coma. Por ejemplo: GET /incapacidades?fields=codigo,codigoTipoIncapacidad,TipoIncapacidad En este caso se espera recibir el código de la incapacidad, el código del tipo de incapacidad y la información del catálogo del tipo de incapacidad asociado. Ya existe una documentación de las propiedades que se pueden acceder de una entidad, que se emplea para redactar las reglas de aplicación de las rutas condicionales, por lo tanto, esta misma especificación podría ser utilizada en este caso.

¿Es útil esta información?
Sí No
En este artículo