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
Exemplo de query com paginação
GET {uri}?page=1&page-size=25
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
Atributos de Resposta
Exemplo de paginação - Apenas uma página
A paginação das APIs são feitas no objeto principal da API. Por exemplo na API de branches, conforme exemplo abaixo, os registros a serem paginados são os objetos "branches". O mesmo deve ser seguido para as demais APIs, por exemplo, "products" nas APIs de produtos, "resources" na API de resources etc.
{
"data": {
"brand": {
"name": "EXEMPLO",
"companies": [
{
"name": "SEGURADORA EXEMPLO",
"cnpjNumber": "123456",
"branches": [
{...},
{...},
{...}
]
}
]
}
},
"links": {
"self": "https://api.seguradora.com.br/open-insurance/channels/v1/branches",
},
"meta": {
"totalRecords": 3,
"totalPages": 1
}
}
Exemplo de paginação - Primeira página
{
"data": {
"..."
},
"links": {
"self": "https://api.seguradora.com.br/open-insurance/channels/v1/branches?page=1&page-size=25",
"next": "https://api.seguradora.com.br/open-insurance/channels/v1/branches?page=2&page-size=25",
"last": "https://api.seguradora.com.br/open-insurance/channels/v1/branches?page=10&page-size=25"
},
"meta": {
"totalRecords": 250,
"totalPages": 10
}
}
Exemplo de paginação - Última Página
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:
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. |
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. |
|
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.
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 opage-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 size800
, a transmissora deve retornar os itens de801
a1600
.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.Se o retorno de uma chamada apresentar um objeto ao invés de uma lista, os campos
totalPages
etotalRecords
deverão ser igual a 1.Para as APIs que possuem o endpoint de withdrawal (resgate) na Fase 2, quando não houver ocorrência de resgate, a paginação retornada deve ser
totalPages
etotalRecords
igual a 1. Esse endpoint será padronizado em correção futura para trazer a mesma estrutura/paginação do endpoint de “portabilities”.Para as APIs que possuem o endpoint de movements (movimentos) na Fase 2, como existem dois objetos principais na chamada, a paginação deve ocorrer sob a soma dos itens retornados em movementsContributions e movementsBenefits, vide exemplo abaixo:
Exemplo:
Lista de movimentos de contribuições: 17 itens retornados
Lista de movimentos de benefícios: 14 itens retornados
Paginação padrão do OPIN descrita na documentação: máximo de 25 itens por página
No exemplo acima, seria necessário 2 páginas para mostrar todos os 31 itens (17+14) presentes na chamada realizada contra o endpoint de movements, onde a primeira página apresentaria 25 registros, e na segunda página teríamos os 6 registros restantes.
Em contrapartida se fosse considerado apenas uma das listas (movementsContribution e movementsBenefits) para a paginação, teríamos somente um página.
Dessa forma fica estabelecido que a paginação do endpoint de movements deve considerar todos os itens presentes nas duas listas, movementsContribution e movementsBenefits.