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

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

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.	Quando chamado o método GET deverá retornar o link para o próprio recurso consultado Quando chamado o método POST deverá retornar o link para o recurso criado Quando chamado método PATCH deverá retornar o link para o recurso alterado

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.

Área do Desenvolvedor

Paginação

Parâmetros de Requisição

Atributos de Resposta

Links

Meta

Regras Adicionais

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.