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

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

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.

Exemplo de paginação - Primeira página

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:

Meta

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

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

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

2. 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.

3. 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.

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

5. 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.

6. 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.

7. Se o retorno de uma chamada apresentar um objeto ao invés de uma lista, os campos totalPages e totalRecords deverão ser igual a 1.

8. 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 e totalRecords igual a 1. Esse endpoint será padronizado em correção futura para trazer a mesma estrutura/paginação do endpoint de “portabilities”.

9. 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:

   1. Exemplo:

      1. Lista de movimentos de contribuições: 17 itens retornados

      2. Lista de movimentos de benefícios: 14 itens retornados

      3. Paginação padrão do OPIN descrita na documentação: máximo de 25 itens por página

         1. 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.

         2. Em contrapartida se fosse considerado apenas uma das listas (movementsContribution e movementsBenefits)  para a paginação, teríamos somente um página.

      4. Dessa forma fica estabelecido que a paginação do endpoint de movements deve considerar todos os itens presentes nas duas listas, movementsContribution e movementsBenefits.