Paginação

Gerenciar grandes conjuntos de dados de forma eficiente é crucial para manter o desempenho e a escalabilidade da API. Nossas APIs empregam um mecanismo robusto de paginação para entregar dados em porções menores e gerenciáveis. Isso melhora os tempos de resposta e o processamento no lado do cliente, particularmente para aplicações que carregam resultados de forma incremental.

Paginação em nossas APIs

Em vez de retornar o conjunto de dados inteiro em uma única resposta, o que pode sobrecarregar recursos, os clientes podem solicitar subconjuntos específicos de dados. Isso melhora os tempos de resposta e permite um tratamento de dados mais suave, particularmente para aplicações que carregam resultados de forma incremental. Suportamos dois parâmetros de consulta para paginação:

page (inteiro): Especifica o número da página a ser recuperada. O valor padrão é 1.
- Valores negativos são inválidos e resultarão em 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 no máximo 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, conforme 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.

Abaixo está 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, os endpoints da API que suportam paginação aceitam no máximo 100 itens por página (limit=100). Essa restrição ajuda a garantir um desempenho ideal e evita tamanhos excessivos de payload. Se seu caso de uso requer a recuperação de um número maior de itens por requisição, você pode substituir esse limite definindo a variável de ambiente MAX_PAGINATION_LIMIT na configuração da sua implantação (arquivo .env).

Aumentar o limite de paginação pode resultar em tempos de resposta mais lentos, dependendo do volume de dados e das condições da infraestrutura. Certifique-se de testar completamente em ambientes de homologação antes de aplicar a mudança em produção.

Para atualizar essa configuração no Kubernetes:

kubectl edit configmap midaz-transaction -n midaz

# Set the new value for MAX_PAGINATION_LIMIT

kubectl rollout restart deployments midaz-transaction -n midaz

O Midaz e todos os seus serviços de plugins herdam esse comportamento.

Paginação baseada em cursor

Alguns endpoints utilizam paginação baseada em cursor em vez de números de página. Essa abordagem é mais eficiente para grandes conjuntos de dados e garante resultados consistentes mesmo quando os dados são modificados entre as requisições. Endpoints com paginação por 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 este parâmetro para começar do início.
limit (inteiro): O número máximo de itens por página. O valor padrão é 10.
sort_order (string): A direção utilizada para ordenar os resultados. Valores aceitos: asc (ascendente, padrão) ou desc (descendente).

Ao paginar com um cursor de uma resposta anterior, não é possível alterar o sort_order durante a paginação. Os parâmetros de ordenação devem ser definidos na requisição inicial e permanecer consistentes ao longo da sequência de paginação.

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 para a página atual.
next_cursor: Um token codificado para recuperar a próxima página. Se ausente ou vazio, não há mais resultados.
prev_cursor: Um token codificado para recuperar a página anterior. Se ausente ou vazio, você está na primeira página.
limit: O número máximo de itens incluídos na resposta.

Para navegar para 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

Abaixo está um exemplo de resposta para uma requisição com paginação 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?

Os seguintes endpoints utilizam paginação baseada em cursor:

Listar Transações — GET /v1/organizations/{id}/ledgers/{id}/transactions
Listar Saldos — GET /v1/organizations/{id}/ledgers/{id}/balances
Listar Operações por Conta — GET /v1/organizations/{id}/ledgers/{id}/accounts/{id}/operations
Listar Tipos de Conta — GET /v1/organizations/{id}/ledgers/{id}/account-types
Listar Rotas de Operação — GET /v1/organizations/{id}/ledgers/{id}/operation-routes
Listar Rotas de Transação — GET /v1/organizations/{id}/ledgers/{id}/transaction-routes

Os demais endpoints de listagem utilizam a paginação padrão baseada em página descrita acima.

Visão geral

Fundamentos de integração

Estabilidade e qualidade

Paginação em nossas APIs

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 em nossas APIs

​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 em nossas APIs

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?