Paginação

Endpoints que retornam listas de recursos suportam paginação. A Catalisa Platform utiliza paginação baseada em offset com parâmetros padronizados.

Parâmetros de Query

Parâmetro	Tipo	Default	Max	Descrição
page[number]	integer	1	-	Número da página (começa em 1)
page[size]	integer	20	100	Quantidade de itens por página

Estrutura da Resposta

Respostas paginadas incluem os objetos meta e links:

{
  "data": [
    { "type": "users", "id": "1", "attributes": { ... } },
    { "type": "users", "id": "2", "attributes": { ... } }
  ],
  "meta": {
    "totalItems": 150,
    "totalPages": 8,
    "currentPage": 1,
    "itemsPerPage": 20,
    "hasNextPage": true,
    "hasPreviousPage": false
  },
  "links": {
    "self": "/api/v1/users?page[number]=1&page[size]=20",
    "first": "/api/v1/users?page[number]=1&page[size]=20",
    "prev": null,
    "next": "/api/v1/users?page[number]=2&page[size]=20",
    "last": "/api/v1/users?page[number]=8&page[size]=20"
  }
}

Meta

Campo	Tipo	Descrição
totalItems	integer	Total de itens disponíveis
totalPages	integer	Total de páginas
currentPage	integer	Página atual
itemsPerPage	integer	Itens por página
hasNextPage	boolean	Indica se existe próxima página
hasPreviousPage	boolean	Indica se existe página anterior

Links

Campo	Tipo	Descrição
self	string	URL da página atual
first	string	URL da primeira página
prev	string | null	URL da página anterior
next	string | null	URL da próxima página
last	string	URL da última página

Exemplos de Uso

Requisição Básica

cURL

curl 'https://api.catalisa.io/iam/api/v1/users?page[number]=2&page[size]=10' \
  -H 'Authorization: Bearer SEU_TOKEN'

JavaScript

const page = 2;
const size = 10;

const response = await fetch(
  `https://api.catalisa.io/iam/api/v1/users?page[number]=${page}&page[size]=${size}`,
  {
    headers: {
      'Authorization': `Bearer ${token}`,
    },
  }
);

const { data, meta, links } = await response.json();
console.log(`Página ${meta.currentPage} de ${meta.totalPages}`);
console.log(`Total: ${meta.totalItems} itens`);

Iterando por Todas as Páginas

JavaScript

async function getAllItems(baseUrl, token) {
  const items = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `${baseUrl}?page[number]=${page}&page[size]=100`,
      {
        headers: {
          'Authorization': `Bearer ${token}`,
        },
      }
    );

    const { data, meta } = await response.json();
    items.push(...data);

    hasMore = meta.hasNextPage;
    page++;
  }

  return items;
}

// Uso
const allUsers = await getAllItems(
  'https://api.catalisa.io/iam/api/v1/users',
  token
);
console.log(`Total de usuários: ${allUsers.length}`);

Usando os Links HATEOAS

JavaScript

async function fetchWithPagination(url, token) {
  const response = await fetch(url, {
    headers: {
      'Authorization': `Bearer ${token}`,
    },
  });

  const { data, meta, links } = await response.json();

  return {
    items: data,
    meta,
    nextUrl: links.next,
    prevUrl: links.prev,
    hasNext: meta.hasNextPage,
    hasPrev: meta.hasPreviousPage,
  };
}

// Navegação
let result = await fetchWithPagination(
  'https://api.catalisa.io/iam/api/v1/users',
  token
);

// Próxima página
if (result.hasNext) {
  result = await fetchWithPagination(result.nextUrl, token);
}

// Página anterior
if (result.hasPrev) {
  result = await fetchWithPagination(result.prevUrl, token);
}

Filtros Combinados

Você pode combinar paginação com filtros específicos de cada endpoint:

# Usuários ativos, página 2, 25 por página
curl 'https://api.catalisa.io/iam/api/v1/users?filter[status]=ativo&page[number]=2&page[size]=25' \
  -H 'Authorization: Bearer SEU_TOKEN'

Boas Práticas

Dicas

1. Use o tamanho adequado: Para listagens em UI, use page[size]=20. Para exportações, use page[size]=100.
2. Aproveite os links: Use os links HATEOAS em vez de construir URLs manualmente.
3. Verifique hasNextPage: Sempre verifique antes de tentar carregar a próxima página.
4. Limite requisições: Implemente rate limiting no cliente para não sobrecarregar a API.

Atenção

• O tamanho máximo por página é 100 itens
• Páginas além do total retornam array vazio em data
• Os links prev e next são null quando não aplicáveis