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:
Parâmetro | Descrição | Valor Padrão |
|---|---|---|
page | Número da página que está sendo requisitada (o valor da primeira página é 1). | 1 |
page-size | Quantidade total de registros por páginas. | 25 |
O valor padrão será assumido sempre que o parâmetro não estiver preenchido ou estiver nulo. |
|---|
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
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:
Parâmetro | Descrição | Restrição |
|---|---|---|
first | A URI para requisitar a primeira página. | Obrigatório se a resposta não for a primeira página. |
last | A URI para requisitar a última página. | Obrigatório se a resposta não for a última página e quando este campo for especificado no endpoint. |
prev | A URI para requisitar a página anterior. | Obrigatório quando houver página anterior. Não deve ser enviado quando for a primeira página. |
next | A URI para requisitar a próxima página. | Obrigatório quando houver página posterior. Não deve ser enviado quando for a última página. |
self | A URI para requisitar a própria página |
|
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
Parâmetro | Descrição | Restrição |
|---|---|---|
totalRecords | O número total de registros da requisição. | Este atributo é obrigatório. |
totalPages | O número total de páginas da requisição. | Este atributo é obrigatório. Se não possuir nenhum registro o valor deve ser 0. |
Para cada um desses atributos o tamanho da página especificado na requisição deverá ser utilizado para o cálculo dos valores. |
|---|
Ú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) é1000registros para qualquer endpoint (a menos que na API esteja especificado outros valores).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 opage-sizedo 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
1000registros, para uma instituição que trabalha com max size800, a transmissora deve retornar os itens de801a1600.
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:Para as APIs de Dados Cadastrais e Transacionais, o comportamento esperado da transmissora/detentora é que o page size mínimo é 25 e o máximo é 1000, exceções se aplicam a primeira página, quando for única, e a última página.
Exemplo: A receptora solicita 5 registros por página, entretanto, a transmissora possui 47 registros. Pelo comportamento descrito, a transmissora retornará 25 registros na primeira página de 22 registros na segunda.