Paginação

A API do ION Guard utiliza paginação cursor-based para navegar por listas de recursos. Este método é mais eficiente que paginação offset-based para datasets grandes e em constante mudança.

Como funciona

Em vez de páginas numeradas (1, 2, 3...), a API retorna um cursor — um token opaco que aponta para a posição no dataset. Você usa o cursor para solicitar a próxima ou anterior página de resultados.

Parâmetros de requisição

Parâmetro	Padrão	Descrição
limit	20	Número de itens por página (máximo: 100)
cursor	—	Token de paginação (obtido na resposta anterior)

Valores de limit acima de 100 são automaticamente reduzidos ao teto de 100.

Filtros por recurso

Alguns endpoints de listagem aceitam filtros adicionais que combinam com a paginação. Por exemplo, GET /api/v1/alerts (e GET /api/v1/sites/{site}/alerts) aceitam:

Filtro	Descrição
type	Filtra por tipo de alerta
severity	Filtra por severidade
status	Filtra por status do alerta

Os filtros são aplicados antes da paginação e mantidos automaticamente nas URLs de links.next / links.prev.

Exemplo de requisição

GET /api/v1/alerts?limit=10
Authorization: Bearer {token}

Formato da resposta

A resposta é envelopada em três blocos: data (os recursos), links (URLs de navegação) e meta (metadados da paginação).

{
  "data": [
    { "id": "9c1a...", "type": "panic", "status": "active", ... },
    { "id": "9c1b...", "type": "device-offline", "status": "acknowledged", ... }
  ],
  "links": {
    "first": null,
    "last": null,
    "prev": null,
    "next": "/api/v1/alerts?cursor=eyJpZCI6MTAsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0&limit=10"
  },
  "meta": {
    "path": "/api/v1/alerts",
    "per_page": 10,
    "next_cursor": "eyJpZCI6MTAsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
    "prev_cursor": null
  }
}

Campo	Descrição
data	Array de recursos da página atual
links.next	URL completa para a próxima página (null se não há mais itens)
links.prev	URL completa para a página anterior (null se é a primeira)
links.first / links.last	Sempre null na paginação cursor-based (não há primeira/última fixas)
meta.path	Caminho base usado para gerar as URLs
meta.per_page	Itens por página solicitados
meta.next_cursor	Cursor para a próxima página (null se não há mais itens)
meta.prev_cursor	Cursor para a página anterior (null se é a primeira)

Navegando entre páginas

# Primeira página
curl -s "https://ionguard.local/api/v1/alerts?limit=10" \
  -H "Authorization: Bearer $TOKEN"

# Próxima página (usando meta.next_cursor da resposta anterior)
curl -s "https://ionguard.local/api/v1/alerts?limit=10&cursor=eyJpZCI6MTAuLi4" \
  -H "Authorization: Bearer $TOKEN"

Fim da lista

Quando meta.next_cursor é null e links.next é null, não há mais itens disponíveis.

Vantagens do cursor-based

• Performance — Não precisa contar todos os registros (O(1) vs O(n))
• Consistência — Inserções e deleções durante a navegação não causam itens duplicados ou pulados
• Escalabilidade — Funciona bem com milhões de registros