Paginare cu cursor la /api/v1/dates: de ce e mai bună decât paginarea cu offset

Publicat pe 02.04.2026 | Actualizat pe 02.04.2026

Context

Pe 24 aprilie 2026, jurnalul de modificări al API-ului Convertesc.ro a introdus suport pentru paginarea cu cursor pe GET /api/v1/dates. La prima vedere, poate părea o schimbare minoră de interfață. În practică, este o îmbunătățire importantă pentru aplicațiile care încarcă treptat liste mari de date și vor consecvență între pagini, mai ales în contexte în care pot apărea valori noi între două cereri consecutive.

Paginarea cu offset este simplu de înțeles, dar are o problemă clasică: dacă setul de date se schimbă între cereri, poți obține salturi sau dubluri. Paginarea cu cursor rezolvă asta prin ancorarea paginii următoare la ultimul element primit, nu la poziția numerică în listă. Pentru o rută cu date ordonate descrescător, acest model oferă o predictibilitate mai bună.

Pentru integratori, adoptarea cursorului înseamnă și o schimbare de logică: nu mai tratezi paginarea ca „pagina 3”, ci ca „continuă de la această valoare de frontieră”. Dacă această regulă e implementată corect în aplicația care consumă API-ul, listarea devine mai robustă în timp.

Cum funcționează

Pe GET /api/v1/dates, poți folosi fie offset, fie cursor, dar nu ambele simultan. Când folosești paginarea cu cursor, trimiți ultima dată din pagina precedentă și primești următoarele rezultate mai vechi. Răspunsul include metadate care indică explicit modul de paginare și, când există, cursorul următor.

Avantajele practice:

1. continuitate mai bună la date dinamice;
2. risc mai mic de elemente duplicate/omise;
3. implementare mai simplă pentru încărcare treptată sau afișare progresivă.

Dezavantajul principal este că verificarea manuală „pe pagini” e mai puțin intuitivă decât la offset. Totuși, pentru aplicații reale, beneficiul de consecvență depășește acest cost.

În implementările mature, recomandarea este să standardizezi paginarea cu cursor în aplicația care consumă API-ul și să păstrezi offset doar pentru compatibilitate punctuală sau unelte interne. Dacă folosești deja historical cu revenire la ultima zi disponibilă, această abordare se aliniază bine cu ideea unui flux determinist bazat pe date explicite.

Pentru contextul endpoint-urilor de curs, vezi articolul despre cursul curent și cursul istoric. Pentru partea de operare și alerte, vezi articolul despre monitorizare și verificări de stare.

Exemplu practic

Prima cerere, în modul cu cursor:

curl "https://convertesc.ro/api/v1/dates?limit=3"

Presupunând că răspunsul conține ultimele trei date, aplicația reține ultima valoare din listă și cere pagina următoare:

curl "https://convertesc.ro/api/v1/dates?limit=3&cursor=2026-04-21"

Exemplu de metadate utile:

{
  "meta": {
    "pagination": "cursor",
    "cursor": "2026-04-21",
    "next_cursor": "2026-04-18"
  }
}

Model simplu în interfață:

1. păstrezi next_cursor în stare;
2. dezactivezi butonul „Încarcă mai mult” când next_cursor este null;
3. elimini dublurile în aplicație după valoarea datei.

În acest mod, chiar dacă între două încărcări intră o dată nouă în sistem, fluxul rămâne coerent. Pentru selecțiile istorice din interfață, această abordare produce listări stabile și ușor de testat.

Greșeli frecvente

Prima greșeală este amestecul parametrilor offset și cursor. Contractul API le tratează ca moduri care se exclud reciproc. Când sunt trimise împreună, răspunsul corect este o eroare de validare. Aplicația trebuie să aleagă explicit unul singur.

A doua greșeală este ignorarea next_cursor și calcularea manuală a următorului cursor. Chiar dacă pare posibil, e fragil și poate rupe ordinea în cazuri limită. Mai robust este să folosești exact valoarea întoarsă de server.

A treia greșeală este lipsa eliminării dublurilor în aplicație. În practică, schimbările de date între cereri pot produce situații de frontieră. O deduplicare simplă după șirul datei evită artefactele vizuale și menține lista curată.

A patra greșeală este neglijarea testelor de integrare pe date reale. Dacă testezi doar local cu un set fix de date, nu observi avantajul cursorului în scenarii dinamice. Leagă aceste teste de monitorizarea descrisă în articolul despre verificările de stare și verifică periodic comportamentul cap-coadă.

Pentru o integrare completă de tip ron fx rates json api, folosește acest ghid împreună cu api curs valutar bnr json: latest și historical, cu api curs valutar cu fallback weekend și cu bnr api health endpoint.

Concluzie

Paginarea cu cursor pe /api/v1/dates este o alegere practică pentru aplicațiile care au nevoie de încărcare treptată și stabilă. Față de offset, reduce riscul de deplasare a listei atunci când setul de date se modifică în timp și se potrivește mai bine cu interfețele moderne.

Pentru o implementare corectă, păstrează regula „un singur mod de paginare”, folosește next_cursor din răspuns și elimină dublurile la nivelul aplicației. Împreună cu endpoint-urile latest și historical, acest model oferă o bază solidă pentru produse care depind de cursuri valutare actualizate și istorice.

În plus, când echipa ta operează mai multe aplicații, păstrează un utilitar comun pentru paginare și validarea răspunsurilor. Refolosirea acestui strat reduce diferențele de comportament între web, mobil și serviciile interne și simplifică mult actualizările atunci când contractul API evoluează.