Paginação

Os endpoints de listagem do Midaz entregam dados em partes menores e gerenciáveis. Isso melhora os tempos de resposta e o processamento no lado do cliente, principalmente para aplicações que carregam resultados de forma incremental. As outras APIs da Lerian definem seus próprios parâmetros, padrões e limites de paginação. Consulte a referência de cada API.

Paginação baseada em página

Em vez de retornar o dataset inteiro em uma única resposta, o que pode sobrecarregar os recursos, os clientes podem solicitar subconjuntos específicos de dados. Os endpoints baseados em página aceitam dois parâmetros de consulta:

page (inteiro): Especifica o número da página a ser recuperada. O valor padrão é 1.
- Valores abaixo de 1 retornam um erro.
limit (inteiro): Define o número máximo de itens por página. O valor padrão é 10.

Por exemplo, para recuperar a primeira página de organizações com um máximo de 10 itens por página:

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

Resposta de paginação

A resposta de paginação inclui a seguinte estrutura:

items: Um array de entidades recuperadas para a página atual. Cada objeto contém informações detalhadas sobre o recurso solicitado, como mostrado no exemplo abaixo.
page: O número da página atual, começando em 1 (padrão).
limit: O número máximo de itens incluídos na resposta, conforme definido na requisição ou na configuração padrão.

Veja abaixo um exemplo de resposta para uma requisição 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
}

Tamanho máximo da página

Por padrão, o Midaz aceita um máximo de 100 itens por página (limit=100). Essa restrição evita tamanhos de payload excessivos. Se o seu caso de uso exigir recuperar um número maior de itens por requisição, você pode sobrescrever esse limite definindo a variável de ambiente MAX_PAGINATION_LIMIT na configuração de deploy (arquivo .env). As listas de pacotes de cobrança mantêm o máximo de 100.

Aumentar o limite de paginação pode resultar em tempos de resposta mais lentos, dependendo do volume de dados e das condições de infraestrutura. Teste bem em ambientes de staging antes de aplicar a mudança em produção.

Depois de alterar o valor, reinicie o Ledger. Para defini-lo em um deploy do Midaz, consulte o README do chart do Midaz.

Paginação baseada em cursor

Alguns endpoints usam paginação baseada em cursor em vez de números de página. Essa abordagem é mais eficiente para datasets grandes ou que mudam com frequência. Os endpoints baseados em cursor aceitam os seguintes parâmetros de consulta:

cursor (string): Um token codificado de uma resposta anterior (next_cursor ou prev_cursor) para navegar para frente ou para trás. Omita esse parâmetro para começar do início.
limit (inteiro): O número máximo de itens por página.
sort_order (string): A direção usada para ordenar os resultados. Valores aceitos: asc (crescente) ou desc (decrescente).

Defina sort_order na requisição inicial e mantenha-o igual enquanto você segue os cursores.

Por exemplo, para recuperar saldos usando paginação por cursor:

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

Resposta da paginação por cursor

A resposta inclui a seguinte estrutura:

items: Um array de entidades da página atual.
next_cursor: Um token codificado para recuperar a próxima página. Se estiver ausente ou vazio, não há mais resultados.
prev_cursor: Um token codificado para recuperar a página anterior. Se estiver ausente ou vazio, você está na primeira página.
limit: O número máximo de itens incluídos na resposta.

Para navegar até a próxima página, passe o valor de next_cursor como o parâmetro de consulta cursor:

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

Veja abaixo um exemplo de resposta para uma requisição paginada 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
}

Quais endpoints usam paginação por cursor?

A referência de cada endpoint na API mostra se ele aceita page ou cursor.

Visão geral

Fundamentos de integração

Estabilidade e qualidade

Dicionário de campos

Streaming de eventos

Paginação baseada em página

Resposta de paginação

Tamanho máximo da página

Paginação baseada em cursor

Resposta da paginação por cursor

Quais endpoints usam paginação por cursor?

​Paginação baseada em página

​Resposta de paginação

​Tamanho máximo da página

​Paginação baseada em cursor

​Resposta da paginação por cursor

​Quais endpoints usam paginação por cursor?

Paginação baseada em página

Resposta de paginação

Tamanho máximo da página

Paginação baseada em cursor

Resposta da paginação por cursor

Quais endpoints usam paginação por cursor?