Paginação

Cada recurso de cada API pode possuir ou não paginação, caso a quantidade de registros retornados justifique a mesma. A paginação estará disponível e deverá funcionar independente se o recurso permite filtros por query ou POST. Isso é, filtros e paginação são aplicados de forma independente.

Parâmetros de Requisição

Quando existir paginação para o recurso deverão ser utilizados os parâmetros de query abaixo para a navegação dos resultados:

Exemplo de query com paginação

GET {uri}?page=1&page-size=25

Atributos de Resposta

Além dos dados requisitados, as respostas paginadas também terão em sua estrutura dois objetos adicionais que incluirão parâmetros para facilitar a navegação das páginas:

Exemplo de paginação

Apenas uma página

{
    "data": {
        "..."
    },
    "links": {
        "self": "https://api.banco.com.br/open-banking/channels/v1/branches",
    },
    "meta": {
        "totalRecords": 1,
        "totalPages": 1
    }
}

Links

Links

O objeto links passará por revisão subsequente de modo a atender as próximas Fases do Open Banking, em especial a partir da Fase 2.

Os links devem sempre ser validados de acordo com o pattern publicado no swagger.

Quando preenchidos devem ter a mesma estrutura (schema, host, api, versão e recurso) do que esta sendo paginado.

No objeto links, serão retornadas hypermedia (referências para os recursos relacionados) de paginação conforme parâmetros abaixo:

Primeira página

{
    "data": {
        "..."
    },
    "links": {
        "self": "https://api.banco.com.br/open-banking/channels/v1/branches?page=1&page-size=25",
        "next": "https://api.banco.com.br/open-banking/channels/v1/branches?page=2&page-size=25",
        "last": "https://api.banco.com.br/open-banking/channels/v1/branches?page=10&page-size=25"
    },
    "meta": {
        "totalRecords": 250,
        "totalPages": 10
    }
}

Meta

No objeto meta, serão retornadas informações sobre o total de registros disponíveis

Última Página

{
"data": {
    "..."
},
"links": {
    "self": "https://api.banco.com.br/open-banking/channels/v1/branches?page=10&page-size=25",
    "first": "https://api.banco.com.br/open-banking/channels/v1/branches?page=1&page-size=25",
    "prev": "https://api.banco.com.br/open-banking/channels/v1/branches?page=9&page-size=25"
},
"meta": {
    "totalRecords": 250,
    "totalPages": 10
}

Regras Adicionais

• O tamanho máximo da página (page-size) é 1000 registros para qualquer endpoint (a menos que na API esteja especificado outros valores).

• A instituição transmissora/detentora pode definir um tamanho máximo da página (page-size) inferior ao tamanho máximo permitido pela API, caso entenda necessário diminuir o limite para atender o SLA de resposta.

• Caso a instituição transmissora/detentora defina um tamanho máximo de página (page-size) inferior, se for requisitado uma quantidade de registros maior do que seu limite operacional, e desde que o valor esteja de acordo o tamanho máximo permitido pela API, esta deverá responder entregando os dados e utilizando o page-size do seu limite operacional definido.

• A instituição transmissora/detentora deve realizar os ajustes de paginação antes de efetivar a consulta:

• Ex: Ao solicitar a segunda pagina 1000 registros, para uma instituição que trabalha com max size 800, a transmissora deve retornar os itens de 801 a 1600.

• Se for requisitado uma quantidade de registros maior que o suportado pela API, o retorno será o código HTTP status code 422 Unprocessable Entity, indicando que o servidor entendeu a requisição, mas não é possível processá-la conforme foi solicitado.