Paginación

Sobre la paginación

La API de Aleluya ofrece parámetros que te permiten navegar entre páginas de resultados, limitar la cantidad de registros devueltos y filtrar grandes conjuntos de recursos.

📘

Confirmar disponibilidad de parámetros por endpoint

Estos parámetros no están disponibles para todos los endpoints. La documentación de referencia de cada endpoint es la fuente de verdad sobre dónde están disponibles la paginación, la búsqueda y los filtros.

Límites

Para preservar un rendimiento óptimo de la API, los conjuntos grandes de recursos devuelven un máximo de 50 resultados por página. Si el número de resultados excede ese límite, la paginación se usa para dividir los resultados en múltiples páginas.

Cuando el parámetro per_page está disponible en un endpoint, puedes establecer el número de recursos que deseas recuperar incluyéndolo como parámetro de consulta en la petición.

Por ejemplo, para limitar el número de resultados a 10:

GET /v1/companies/{company_id}/payments?per_page=10

Content-Type: application/json
Accept: application/json
Cookie: token=TU_TOKEN; refresh_token=TU_REFRESH_TOKEN

Paginación

La API usa paginación basada en offset (desplazamiento) para organizar grandes conjuntos de recursos en páginas y permitir su navegación.

Cuando los resultados se devuelven en múltiples páginas, verás un objeto filters en la respuesta que contiene información sobre la paginación.

Estructura de la respuesta

{
  "data": [
      …
  ],
  "filters": {
    "total_records": 150,
    "page": 2,
    "per_page": 10,
    "search": ""
  }
}

Campos del objeto filters

Parámetros de paginación

Navegar entre páginas

Para navegar a la siguiente página, incluye el parámetro page con el número de página deseado en tu petición.

Por ejemplo, para obtener la segunda página:

GET /v1/companies/{company_id}/payments?page=2&per_page=10

Content-Type: application/json
Accept: application/json
Cookie: token=TU_TOKEN; refresh_token=TU_REFRESH_TOKEN

Esto devolverá la siguiente página de resultados para el endpoint dado.

Validaciones

La API valida y ajusta automáticamente los parámetros:

• page: Si no se proporciona, es 0 o negativo, se establece en 1. El máximo permitido es 9999.
• per_page: Si no se proporciona, se usa 20 (valor por defecto). El valor se limita entre 1 y 50 registros por página.

Búsqueda

El parámetro search te permite filtrar resultados por texto. La búsqueda funciona en múltiples campos dependiendo del endpoint.

Cuando el parámetro search está disponible, puedes incluirlo como parámetro de consulta en tu petición:

GET /v1/companies/{company_id}/workers?search=maria&page=1&per_page=20

Content-Type: application/json
Accept: application/json
Cookie: token=TU_TOKEN; refresh_token=TU_REFRESH_TOKEN

La búsqueda se aplica antes de la paginación, por lo que total_records en la respuesta reflejará solo los registros que coinciden con el término de búsqueda.

Filtrado

Opciones de filtrado adicionales pueden estar disponibles para algunos endpoints, según corresponda, dependiendo del modelo de datos.

El parámetro filter permite aplicar filtros específicos según el endpoint. Los valores válidos dependen de cada endpoint. Para más información sobre los filtros disponibles, consulta la documentación de referencia del endpoint que te interesa.

Ejemplo de uso:

GET /v1/companies/{company_id}/workers?filter=active&page=1&per_page=20

Content-Type: application/json
Accept: application/json
Cookie: token=TU_TOKEN; refresh_token=TU_REFRESH_TOKEN

Mejores prácticas

Calcular el total de páginas

Usa total_records y per_page para determinar cuántas páginas hay disponibles:

const totalPages = Math.ceil(response.filters.total_records / response.filters.per_page);
const hasMorePages = response.filters.page < totalPages;

int totalPages = (int) Math.ceil((double) response.getFilters().getTotalRecords() / response.getFilters().getPerPage());
boolean hasMorePages = response.getFilters().getPage() < totalPages;

total_pages = math.ceil(response['filters']['total_records'] / response['filters']['per_page'])
has_more_pages = response['filters']['page'] < total_pages

total_pages = (response[:filters][:total_records].to_f / response[:filters][:per_page]).ceil
has_more_pages = response[:filters][:page] < total_pages

Manejar páginas vacías

Siempre verifica si data está vacío antes de procesar los resultados. Esto puede ocurrir cuando:

• Solicitas una página que no existe
• Los filtros no devuelven resultados
• Es la última página y tiene menos registros que per_page

Usar valores razonables para per_page

Aunque el máximo es 50, considera usar valores más pequeños (10-20) para:

• Mejorar el tiempo de respuesta
• Reducir el consumo de ancho de banda
• Mejorar la experiencia del usuario en aplicaciones móviles

Combinar búsqueda, filtros y paginación

La paginación funciona perfectamente con search y filter. Puedes combinar todos estos parámetros en una sola petición:

GET /v1/companies/{company_id}/workers?search=juan&filter=active&page=1&per_page=20