Pular para o conteúdo principal
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.