Paginación

Paginación basada en páginas en los endpoints de lista de Lerian, con los parámetros de consulta page y limit y un payload de respuesta paginada consistente para cada recurso.

Nuestras APIs usan paginación para entregar los datos en porciones más pequeñas y manejables. Esto mejora los tiempos de respuesta y el procesamiento del lado del cliente, en particular para aplicaciones que cargan resultados de forma incremental.

​

Paginación en nuestras APIs

---

En lugar de devolver todo el conjunto de datos en una sola respuesta, lo que puede sobrecargar los recursos, los clientes pueden solicitar subconjuntos específicos de datos.

Admitimos dos parámetros de consulta para la paginación:

• page (entero): especifica el número de página que se recuperará. El valor predeterminado es 1.
  • Los valores negativos no son válidos y generan un error.
• limit (entero): define la cantidad máxima de elementos por página. El valor predeterminado es 10.

Por ejemplo, para recuperar la primera página de organizaciones con un máximo de 10 elementos por página:

HTTP

GET /v1/organizations?page=1&limit=10

​

Respuesta de paginación

La respuesta de paginación incluye la siguiente estructura:

• items: un arreglo de entidades recuperadas para la página actual. Cada objeto contiene información detallada sobre el recurso solicitado, como se muestra en el ejemplo a continuación.
• page: el número de página actual, a partir de 1 (predeterminado).
• limit: la cantidad máxima de elementos incluidos en la respuesta, según lo definido en la solicitud o en la configuración predeterminada.

A continuación se muestra un ejemplo de respuesta para una solicitud paginada:

JSON

{
    "items": [
        {
            "id": "0193696f-8eff-7926-a77a-0b424cf7156b",
            "parentOrganizationId": null,
            "legalName": "Collins Inc",
            "doingBusinessAs": "The ledger.io",
            "legalDocument": "78425230000190",
            "address": {
                "line1": "Avenida Paulista, 1234",
                "line2": "CJ 203",
                "zipCode": "01310916",
                "city": "New Lyla",
                "state": "CH",
                "country": "FO"
            },
            "status": {
                "code": "ACTIVE",
                "description": "Ledger Test"
            },
            "createdAt": "2024-11-26T17:05:39.071587Z",
            "updatedAt": "2024-11-26T17:05:39.071587Z",
            "deletedAt": null,
            "metadata": {
                "bitcoinn": "3QH2XV7JxMRKXDqh87JG7LWuf7AeGfy",
                "boolean": true,
                "chave": "metadata_chave",
                "double": 10.5,
                "int": 1
            }
        }
    ],
    "page": 1,
    "limit": 1
}

​

Tamaño máximo de página

De forma predeterminada, los endpoints de la API que admiten paginación aceptan un máximo de 100 elementos por página (limit=100). Esta restricción evita tamaños de payload excesivos.

Si tu caso de uso requiere recuperar una cantidad mayor de elementos por solicitud, puedes anular este límite configurando la variable de entorno MAX_PAGINATION_LIMIT en tu configuración de despliegue (archivo .env).

Aumentar el límite de paginación puede generar tiempos de respuesta más lentos según el volumen de datos y las condiciones de la infraestructura. Prueba exhaustivamente en entornos de staging antes de aplicar el cambio en producción.

Para actualizar esta configuración en Kubernetes:

bash

kubectl edit configmap midaz-ledger -n midaz

# Set the new value for MAX_PAGINATION_LIMIT

kubectl rollout restart deployments midaz-ledger -n midaz

En una instalación gestionada con Helm, configura ledger.configmap.MAX_PAGINATION_LIMIT en tu values.yaml y ejecuta helm upgrade. La siguiente actualización del chart reemplaza una edición directa del ConfigMap.

Midaz y todos sus servicios de plugins heredan este comportamiento.

​

Paginación basada en cursor

---

Algunos endpoints usan paginación basada en cursor en lugar de números de página. Este enfoque es más eficiente para conjuntos de datos grandes o que cambian con frecuencia, y garantiza resultados consistentes incluso cuando los datos se modifican entre solicitudes.

Los endpoints basados en cursor admiten los siguientes parámetros de consulta:

• cursor (cadena): un token codificado de una respuesta anterior (next_cursor o prev_cursor) para navegar hacia adelante o hacia atrás. Omite este parámetro para empezar desde el principio.
• limit (entero): la cantidad máxima de elementos por página. El valor predeterminado es 10.
• sort_order (cadena): la dirección usada para ordenar los resultados. Valores aceptados: asc (ascendente, predeterminado) o desc (descendente).

Cuando pagines con un cursor de una respuesta anterior, no puedes cambiar sort_order a mitad de la paginación. Configura los parámetros de ordenamiento en la solicitud inicial y mantenlos consistentes durante toda la secuencia de paginación.

Por ejemplo, para recuperar saldos usando paginación por cursor:

HTTP

GET /v1/organizations/{organization_id}/ledgers/{ledger_id}/balances?limit=10

​

Respuesta de paginación por cursor

La respuesta incluye la siguiente estructura:

• items: un arreglo de entidades para la página actual.
• next_cursor: un token codificado para recuperar la siguiente página. Si está ausente o vacío, no hay más resultados.
• prev_cursor: un token codificado para recuperar la página anterior. Si está ausente o vacío, estás en la primera página.
• limit: la cantidad máxima de elementos incluidos en la respuesta.

Para navegar a la página siguiente, pasa el valor de next_cursor como el parámetro de consulta cursor:

HTTP

GET /v1/organizations/{organization_id}/ledgers/{ledger_id}/balances?cursor=eyJpZCI6IjAxOTNiN...&limit=10

A continuación se muestra un ejemplo de respuesta para una solicitud paginada por cursor:

JSON

{
    "items": [
        {
            "id": "019c96a0-0c0d-7915-84b9-e497bfee9916",
            "organizationId": "019c96a0-0a98-7287-9a31-786e0809c769",
            "ledgerId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
            "accountId": "019c96a0-0c0c-7221-8cf3-13313fb60081",
            "alias": "customer-brl-1",
            "key": "default",
            "assetCode": "BRL",
            "available": "1000",
            "onHold": "0"
        }
    ],
    "next_cursor": "eyJpZCI6IjAxOTNiNTZmLWJhY2YtNzQ0MS05NDU4LTEyZTE5MjVlOGI4NCIsInBvaW50c19uZXh0Ijp0cnVlfQ==",
    "prev_cursor": "eyJpZCI6IjAxOTNiNTZmLWJhY2YtNzQ0MS05NDU4LTEyZTE5MjVlOGI4NCIsInBvaW50c19uZXh0IjpmYWxzZX0=",
    "limit": 10
}

​

¿Qué endpoints usan paginación por cursor?

Los siguientes endpoints usan paginación basada en cursor:

• Listar transacciones: GET /v1/organizations/{id}/ledgers/{id}/transactions
• Listar saldos: GET /v1/organizations/{id}/ledgers/{id}/balances
• Listar operaciones por cuenta: GET /v1/organizations/{id}/ledgers/{id}/accounts/{id}/operations
• Listar tipos de cuenta: GET /v1/organizations/{id}/ledgers/{id}/account-types
• Listar rutas de operación: GET /v1/organizations/{id}/ledgers/{id}/operation-routes
• Listar rutas de transacción: GET /v1/organizations/{id}/ledgers/{id}/transaction-routes

Todos los demás endpoints de listado usan la paginación estándar basada en páginas descrita anteriormente.