Paginate (auto-aggregate)

Descrizione

Iteratore enterprise per REST API paginate che gestisce automaticamente la complessità del looping attraverso N pagine fino al recupero completo del dataset, aggregando tutti i risultati in un singolo array unificato. Le REST API moderne implementano almeno 4 schemi di paginazione mutuamente incompatibili (causa di frustrazione storica per chi le integra a mano): (1) cursor-based — la più moderna e scalabile, usata da Shopify, Stripe, GitHub v4 GraphQL — la response contiene un opaque cursor "abc123" che va passato come query string `?cursor=abc123` nella next request, fino a quando il cursor è null/missing; (2) page-number — il più semplice e usato da CMS WordPress, Magento, e legacy enterprise — la response porta total_pages oppure has_more, e si itera `?page=1`, `?page=2`, ..., `?page=N`; (3) offset-limit — il classico SQL OFFSET/LIMIT esposto come `?offset=0&limit=50`, `?offset=50&limit=50`, semplice ma inefficace su dataset grossi (offset 100k è O(N) sul server); (4) link-header — il pattern RFC 5988 usato da GitHub v3 REST e altri — la response header `Link: <url>; rel="next"` punta esplicitamente al next URL senza dover costruirlo manualmente. La strategia è ESPLICITA (la scegli nel dropdown, non c'è auto-detect): per la maggior parte delle API sai già quale schema usano. Path JSON configurabile per estrarre l'array dall'envelope della response (es. "data", "results.records" per API nested). Safety cap: max pagine (default 100), max elementi totali (default 50k — protezione memoria), max durata totale (default 5 min — anti-stuck). Rate-limit aware: su HTTP 429 rispetta l'header Retry-After (capped a 30s) e ritenta la stessa pagina fino a 3 volte. SSRF-safe (safe-outbound-fetch). Output: { items (array unificato), pages (pagine processate), totalCount (= items.length), requestsCount (fetch totali, inclusi i retry 429), truncated (true se un cap ha fermato l'iterazione → mancano dati), finalCursor (ultimo cursore visto, solo strategy=cursor) }. Use case: scarica TUTTI gli ordini Shopify delle ultime 24h via cursor-based pagination con filtro updated_at_min (3000+ ordini su un sabato sera black friday → 60 pagine × 50 record → 4-6 minuti); tutti i contatti HubSpot del workspace (offset 100k+ record di customer database B2B per esportazione mensile); tutta la lista commenti GitHub di un repository per analytics community engagement (link-header); bulk export CRM Pipedrive senza scrivere il loop manuale a mano col rischio di off-by-one o cursor-stuck-in-loop; sync incremental Notion database dove vogliamo tutti i record cambiati dall'ultimo cursor salvato in memory_note.

⚙️ Parametri di configurazione

Campi mostrati nell’editor quando si configura il nodo. Generati direttamente dal NodeDefconfigFields.

💡 Esempio configurazione

Snippet JSON del nodo come compare nel workflow. I valori sono derivati daidefaultValue e dai parametri required.

{
  "id": "node-logic_paginate-1",
  "defId": "logic_paginate",
  "label": "Paginate (auto-aggregate)",
  "config": {
    "urlTemplate": "https://api.example.com/items?page={{page}}",
    "method": "GET",
    "pageStrategy": "page-number",
    "limit": 50,
    "maxPages": 100,
    "maxItems": 50000,
    "maxDurationMs": 300000
  }
}

🔗 Nodi correlati nella stessa categoria