Saltar al contenido principal
Gestionar eficientemente grandes conjuntos de datos es crucial para mantener el rendimiento y la escalabilidad de la API. Nuestras APIs emplean un mecanismo robusto de paginación para entregar datos en porciones más pequeñas y manejables. Esto mejora los tiempos de respuesta y el procesamiento del lado del cliente, particularmente para aplicaciones que cargan resultados incrementalmente.

​
Paginación en nuestras APIs

En lugar de devolver el conjunto de datos completo en una sola respuesta, lo que puede sobrecargar los recursos, los clientes pueden solicitar subconjuntos específicos de datos. Esto mejora los tiempos de respuesta y permite un manejo de datos más fluido, particularmente para aplicaciones que cargan resultados incrementalmente. Admitimos dos parámetros de consulta para la paginación:
  • page (integer): Especifica el número de página a recuperar. El valor predeterminado es 1.
    • Los valores negativos son inválidos y resultarán en un error.
  • limit (integer): Define el número máximo 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: 
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, comenzando desde 1 (predeterminado).
  • limit: El número máximo de elementos incluidos en la respuesta, como se define en la solicitud o configuración predeterminada.
A continuación se muestra un ejemplo de respuesta para una solicitud paginada: 
{
    "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

Por defecto, los endpoints de API que admiten paginación aceptan un máximo de 100 elementos por página (limit=100). Esta restricción ayuda a garantizar un rendimiento óptimo y evita tamaños de payload excesivos. Si su caso de uso requiere recuperar un mayor número de elementos por solicitud, puede anular este límite configurando la variable de entorno MAX_PAGINATION_LIMIT en su configuración de despliegue (archivo .env).
Aumentar el límite de paginación puede resultar en tiempos de respuesta más lentos dependiendo del volumen de datos y las condiciones de la infraestructura. Asegúrese de probar exhaustivamente en entornos de staging antes de aplicar el cambio en producción.
Para actualizar esta configuración en Kubernetes: 
kubectl edit configmap midaz-transaction -n midaz

# Establezca el nuevo valor para MAX_PAGINATION_LIMIT

kubectl rollout restart deployments midaz-transaction -n midaz
Midaz y todos sus servicios de plugin heredan este comportamiento.

​
Paginación basada en cursor

Algunos endpoints utilizan paginación basada en cursor en lugar de números de página. Este enfoque es más eficiente para grandes conjuntos de datos y garantiza resultados consistentes incluso cuando los datos cambian entre solicitudes. Los endpoints con paginación por cursor aceptan los siguientes parámetros de consulta:
  • cursor (string): Un token codificado de una respuesta anterior (next_cursor o prev_cursor) para navegar hacia adelante o hacia atrás. Omita este parámetro para comenzar desde el inicio.
  • limit (entero): El número máximo de elementos por página. El valor predeterminado es 10.
  • sort_order (string): La dirección utilizada para ordenar los resultados. Valores aceptados: asc (ascendente, predeterminado) o desc (descendente).
Al paginar con un cursor de una respuesta anterior, no es posible cambiar el sort_order durante la paginación. Los parámetros de ordenamiento deben definirse en la solicitud inicial y permanecer consistentes a lo largo de la secuencia de paginación.
Por ejemplo, para recuperar saldos usando paginación por cursor: 
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á en la primera página.
  • limit: El número máximo de elementos incluidos en la respuesta.
Para navegar a la siguiente página, pase el valor de next_cursor como parámetro de consulta cursor: 
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 con paginación por cursor: 
{
    "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 utilizan 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 utilizan la paginación estándar basada en página descrita anteriormente.